[monitor] README + samples _ ci.yml #15288
Conversation
rakshith91
requested review from
danieljurek,
lmazuel,
mayurid and
mitchdenny
as code owners
| @@ -1,13 +1,179 @@ | |||
| # Azure Opentelemetry Exporter for Monitor | |||
| # Microsoft Opentelemtry Exporter for Azure Monitor client library for Python | |||
There was a problem hiding this comment.
Actually I believe there is a gitter for Azure SDK, we can deprecate the old one and use the SDK one now
https://gitter.im/Azure/azure-sdk-for-python
| ## Troubleshooting | ||
|
|
||
| ### Logging | ||
|
|
||
| - Enable by setting `logging_enable=True` when creating the client. |
There was a problem hiding this comment.
This could confuse users here, need to add details about logging of the actual library, sounds like a magic flag that will enable sending logging telemetry
There was a problem hiding this comment.
i believe this should actually be removed for now
| print("Hello, World!") | ||
| ``` | ||
|
|
||
| ### Batch Export Span Processor |
There was a problem hiding this comment.
Both examples you have in here are actually using BatchExportSpanProcessor, this is example is about using instrumentors, we need extra details like original readme to make clear what the example is covering
https://github.com/microsoft/opentelemetry-azure-monitor-python#instrumentations
| The following sections provide several code snippets covering some of the most common tasks, including: | ||
|
|
||
| * [Export hello world trace data](#export-hello-world-trace) | ||
| * [Batch Export Spans](#batch-export-span-processor) |
There was a problem hiding this comment.
Modifying traces is a bid deal for our customers, please add the example as well
https://github.com/microsoft/opentelemetry-azure-monitor-python#modifying-traces
|
|
||
| Please find further examples in the [samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples) directory demonstrating common scenarios. | ||
|
|
||
| ### Additional documentation |
There was a problem hiding this comment.
What about the auto generated documentation? similar to https://azuresdkdocs.blob.core.windows.net/$web/python/azure-mgmt-monitor/1.0.1/index.html
There was a problem hiding this comment.
We do have the API ref docs link right on top of the page. The intention of theseadditional docs are more to give an in depth idea of the service, ot etc.
| @@ -1,13 +1,179 @@ | |||
| # Azure Opentelemetry Exporter for Monitor | |||
| # Microsoft Opentelemtry Exporter for Azure Monitor client library for Python | |||
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
|
|
||
| ### Authenticate the client | ||
|
|
||
| Interaction with Azure monitor exporter starts with an instance of the `AzureMonitorSpanExporter` class. You will need an **instrumentation_key** or a **connection_string** to instantiate the object. |
There was a problem hiding this comment.
If we are moving towards the use of connection string, would it be better to omit anything related to instrumentation key and only recommend connection string?
There was a problem hiding this comment.
I agree with that tbh! There should be one - and preferably only one obvious way to do it :)
Let's stop documenting it in the readme for this beta but still support it, that way we dont break much stuff on the day of the release but will not encourage users to use it.
| ```Python | ||
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||
| exporter = AzureMonitorSpanExporter( | ||
| connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"] |
There was a problem hiding this comment.
I believe the original sdks used APPLICATIONINSIGHTS_CONNECTION_STRING and APPINSIGHTS_INSTRUMENTATIONKEY?
There was a problem hiding this comment.
yup, we changed these in the samples, so just being consistent
There was a problem hiding this comment.
Wouldn't this be a breaking change if user's are instrumented with both old SDKs and OT sdk? That means they would have to have 2 environment variables to represent the same thing.
There was a problem hiding this comment.
fair enough - changed it
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
| * Your callback function can return False if you do not want this envelope exported. | ||
| * Your callback function must accept an envelope data type as its parameter. | ||
| * You can see the schema for Azure Monitor data types in the envelopes here. | ||
| * The AzureMonitorSpanExporter handles Data data types. |
There was a problem hiding this comment.
I would link to the code in which defines "Data"
|
|
||
| * Create an Azure Monitor resource and get the instrumentation key, more information can be found here. | ||
| * Install the requests integration package using pip install opentelemetry-ext-http-requests. | ||
| * Specify your connection string in an environment variable `AZURE_MONITOR_CONNECTION_STRING`. |
There was a problem hiding this comment.
Isn't this step already explained above?
There was a problem hiding this comment.
agreed - this has become redundant
|
|
||
| This example shows how to instrument with the requests_ library. | ||
|
|
||
| * Create an Azure Monitor resource and get the instrumentation key, more information can be found here. |
There was a problem hiding this comment.
Don't think the exporter README should contain anything about setting up the App Insights resource.
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
|
|
||
| OpenTelemetry also supports several instrumentations which allows to instrument with third party libraries. | ||
|
|
||
| This example shows how to instrument with the requests_ library. |
There was a problem hiding this comment.
Is requests_ linking to anything?
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||
|
|
||
| # Callback function to add os_type: linux to span properties | ||
| def callback_function(envelope): |
There was a problem hiding this comment.
The telemetry processor should not be in the simple example.
|
|
||
| trace.set_tracer_provider(TracerProvider()) | ||
| tracer = trace.get_tracer(__name__) | ||
| RequestsInstrumentor().instrument() |
There was a problem hiding this comment.
I would comment a comment for this line saying something like: This line causes your calls made with the requests library to be tracked.
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
Outdated
Show resolved
Hide resolved
sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Scott Beddall <45376673+scbedd@users.noreply.github.com>
…ME.md Co-authored-by: Leighton Chen <lechen@microsoft.com>
…ME.md Co-authored-by: Leighton Chen <lechen@microsoft.com>
rakshith91
force-pushed
the
otexpreadme
branch
from
3598e7a
to
e58a295
Compare
Co-authored-by: Leighton Chen <lechen@microsoft.com>
| ### Prerequisites: | ||
| To use this package, you must have: | ||
| * Azure subscription - [Create a free account][azure_sub] | ||
| * Azure Monitor - [How to use application insights][application_insights_namespace] |
There was a problem hiding this comment.
Is this really a prerequisite? Also Azure Monitor - How to use Application Insights is kind of confusing. Shouldn't we be only introducing Azure Monitor?
|
|
||
| * [Opentelemetry][opentelemtry_spec]: Opentelemetry is a set of libraries used to collect and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. | ||
|
|
||
| * [Instrumentation][instrumentation_library]: The ability to call the opentelemetry API directly by any application is facilitated by instrumentaton. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library. |
There was a problem hiding this comment.
| * [Instrumentation][instrumentation_library]: The ability to call the opentelemetry API directly by any application is facilitated by instrumentaton. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library. | |
| * [Instrumentation][instrumentation_library]: The ability to track calls made by a Python library is facilitated by instrumentations. A library that enables OpenTelemetry observability for one of these Python libraries is called an Instrumentation Library. |
There was a problem hiding this comment.
I would also link to the supported instrumentation libraries that Python supports. https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/instrumentation
…into new_polling * 'master' of https://github.com/Azure/azure-sdk-for-python: (281 commits) [Communication] Add variable groups necessary for using new azure subscription (Azure#15213) Sync eng/common directory with azure-sdk-tools for PR 1153 (Azure#15322) [Communication] Update version for Preview 3 release (Azure#15317) Increment package version after release of azure_data_tables (Azure#15291) [monitor] README + samples _ ci.yml (Azure#15288) refdoc aka.ms link was broken and silently redirecting, have replaced with azuresdkdocs link as is used in other SDKs. (Azure#15169) Sync eng/common directory with azure-sdk-tools for PR 1202 (Azure#15297) Updating OT exporter to consume latest version of OpenTelemetry API/SDK (Azure#15289) Change live test resource DeleteAfterHours tag to 8 hours (Azure#15294) Add Invoke-DevOpsAPI.ps1, Add functions for Canceling and Listing Builds (Azure#15013) The original one is removed. Point to the new one (Azure#15287) Sync eng/common directory with azure-sdk-tools for PR 1170 (Azure#15087) Adding OpenTelemetry exporter code (Azure#14784) update external link (Azure#15273) Remove invalid characters in basename sourced from username (Azure#15268) Sync eng/common directory with azure-sdk-tools for PR 1188 (Azure#15267) Increment version for core releases (Azure#15269) Increment package version after release of azure_identity (Azure#15266) Fix CI (Azure#15265) Increment package version after release of azure_eventgrid (Azure#15262) ...
Update readme.python.md (Azure#15288)
No description provided.