[monitor] README + samples _ ci.yml #15288
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,13 +1,219 @@ | ||||||
| # Microsoft Opentelemetry exporter for Azure Monitor | ||||||
|
|
||||||
| [](https://gitter.im/Azure/azure-sdk-for-python) | ||||||
|
|
||||||
| The exporter for Azure Monitor allows you to export tracing data utilizing the OpenTelemetry SDK and send telemetry data to Azure Monitor for applications written in Python. | ||||||
|
|
||||||
| [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor) | [Package (PyPi)][pypi] | [API reference documentation][api_docs] | [Product documentation][product_docs] | [Samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples) | [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/CHANGELOG.md) | ||||||
|
|
||||||
| > **NOTE**: This is the preview for the next major version of [`opentelemetry-azure-monitor-python`](https://github.com/microsoft/opentelemetry-azure-monitor-python). | ||||||
|
|
||||||
| ## Getting started | ||||||
|
|
||||||
| ### Install the package | ||||||
|
|
||||||
| Install the Microsoft Opentelemetry exporter for Azure Monitor with [pip][pip]: | ||||||
|
|
||||||
| ```Bash | ||||||
| pip install microsoft-opentelemetry-exporter-azuremonitor --pre | ||||||
| ``` | ||||||
|
|
||||||
| ### 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] | ||||||
| * Opentelemetry SDK - [Opentelemtry SDK for Python][ot_sdk_python] | ||||||
| * Python 3.5 or later - [Install Python][python] | ||||||
|
|
||||||
| ### Authenticate the client | ||||||
|
|
||||||
| Interaction with Azure monitor exporter starts with an instance of the `AzureMonitorSpanExporter` class. You will need a **connection_string** to instantiate the object. | ||||||
| Please find the samples linked below for demonstration as to how to authenticate using a connection string. | ||||||
|
|
||||||
| #### [Create Exporter from connection string][sample_authenticate_client_connstr] | ||||||
|
|
||||||
| ```Python | ||||||
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||||||
| exporter = AzureMonitorSpanExporter( | ||||||
| connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "] | ||||||
| ) | ||||||
| ``` | ||||||
|
|
||||||
| ## Key concepts | ||||||
|
|
||||||
| Some of the key concepts for the Azure monitor exporter include: | ||||||
|
|
||||||
| * [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.
Suggested change
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 |
||||||
|
|
||||||
| * [Trace][trace_concept]: Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship. | ||||||
|
|
||||||
| * [Tracer Provider][tracer_provider]: Provides a `Tracer` for use by the given instrumentation library. | ||||||
|
|
||||||
| * [Span Processor][span_processor]: A span processor allows hooks for SDK's `Span` start and end method invocations. Follow the link for more information. | ||||||
|
|
||||||
| * [Sampling][sampler_ref]: Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend. | ||||||
|
|
||||||
| * [AzureMonitorSpanExporter][client_reference]: This is the class that is initialized to send tracing related telemetry to Azure Monitor. | ||||||
|
|
||||||
| * [Exporter Options][exporter_options]: Options to configure Azure exporters. Includes connection_string, instrumentation_key, proxies, timeout etc. | ||||||
lzchen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
lzchen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| For more information about these resources, see [What is Azure Monitor?][product_docs]. | ||||||
|
|
||||||
| ## Examples | ||||||
|
|
||||||
| The following sections provide several code snippets covering some of the most common tasks, including: | ||||||
|
|
||||||
| * [Exporting a custom span](#export-hello-world-trace) | ||||||
| * [Modifying spans](#modifying-traces) | ||||||
| * [Using an instrumentation to track a library](#instrumentation-with-requests-library) | ||||||
|
|
||||||
|
|
||||||
| ### Export Hello World Trace | ||||||
|
|
||||||
| ```Python | ||||||
| import os | ||||||
| from opentelemetry import trace | ||||||
| from opentelemetry.sdk.trace import TracerProvider | ||||||
| from opentelemetry.sdk.trace.export import BatchExportSpanProcessor | ||||||
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||||||
|
|
||||||
| exporter = AzureMonitorSpanExporter( | ||||||
| connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "] | ||||||
| ) | ||||||
|
|
||||||
| trace.set_tracer_provider(TracerProvider()) | ||||||
lzchen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| tracer = trace.get_tracer(__name__) | ||||||
| span_processor = BatchExportSpanProcessor(exporter) | ||||||
| trace.get_tracer_provider().add_span_processor(span_processor) | ||||||
|
|
||||||
| with tracer.start_as_current_span("hello"): | ||||||
| print("Hello, World!") | ||||||
| ``` | ||||||
|
|
||||||
| ### Modifying Traces | ||||||
|
|
||||||
| * You can pass a callback function to the exporter to process telemetry before it is exported. | ||||||
| * 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" |
||||||
|
|
||||||
| ```Python | ||||||
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||||||
| from opentelemetry import trace | ||||||
| from opentelemetry.sdk.trace import TracerProvider | ||||||
| from opentelemetry.sdk.trace.export import BatchExportSpanProcessor | ||||||
|
|
||||||
| # Callback function to add os_type: linux to span properties | ||||||
| def callback_function(envelope): | ||||||
| envelope.data.baseData.properties['os_type'] = 'linux' | ||||||
| return True | ||||||
|
|
||||||
| exporter = AzureMonitorSpanExporter( | ||||||
| connection_string='InstrumentationKey=<your-ikey-here>' | ||||||
| ) | ||||||
| # This line will modify telemetry | ||||||
| exporter.add_telemetry_processor(callback_function) | ||||||
|
|
||||||
| trace.set_tracer_provider(TracerProvider()) | ||||||
| tracer = trace.get_tracer(__name__) | ||||||
| span_processor = BatchExportSpanProcessor(exporter) | ||||||
| trace.get_tracer_provider().add_span_processor(span_processor) | ||||||
|
|
||||||
| with tracer.start_as_current_span('hello'): | ||||||
| print('Hello World!') | ||||||
| ``` | ||||||
|
|
||||||
| ### Instrumentation with requests library | ||||||
|
|
||||||
| OpenTelemetry also supports several instrumentations which allows to instrument with third party libraries. | ||||||
|
|
||||||
| This example shows how to instrument with the [requests](https://pypi.org/project/requests/) library. | ||||||
|
|
||||||
| * Install the requests integration package using pip install opentelemetry-instrumentation-requests. | ||||||
|
|
||||||
| ```Python | ||||||
| import os | ||||||
| import requests | ||||||
| from opentelemetry import trace | ||||||
| from opentelemetry.instrumentation.requests import RequestsInstrumentor | ||||||
| from opentelemetry.sdk.trace import TracerProvider | ||||||
| from opentelemetry.sdk.trace.export import BatchExportSpanProcessor | ||||||
|
|
||||||
| from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter | ||||||
|
|
||||||
| trace.set_tracer_provider(TracerProvider()) | ||||||
| tracer = trace.get_tracer(__name__) | ||||||
|
|
||||||
| # This line causes your calls made with the requests library to be tracked. | ||||||
| RequestsInstrumentor().instrument() | ||||||
|
There was a problem hiding this comment. I would comment a comment for this line saying something like: |
||||||
| span_processor = BatchExportSpanProcessor( | ||||||
| AzureMonitorSpanExporter( | ||||||
| connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "] | ||||||
| ) | ||||||
| ) | ||||||
| trace.get_tracer_provider().add_span_processor(span_processor) | ||||||
|
|
||||||
| RequestsInstrumentor().instrument() | ||||||
|
|
||||||
| # This request will be traced | ||||||
| response = requests.get(url="https://azure.microsoft.com/") | ||||||
| ``` | ||||||
|
|
||||||
| ## Troubleshooting | ||||||
|
|
||||||
| The exporter raises exceptions defined in [Azure Core](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#azure-core-library-exceptions). | ||||||
|
|
||||||
| ## Next steps | ||||||
|
|
||||||
| ### More sample code | ||||||
|
|
||||||
| 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. |
||||||
|
|
||||||
| For more extensive documentation on the Azure Monitor service, see the [Azure Monitor documentation][product_docs] on docs.microsoft.com. | ||||||
|
|
||||||
| For detailed overview of Opentelemetry, visit their [overview](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md) page. | ||||||
|
|
||||||
| ## Contributing | ||||||
|
|
||||||
| This project welcomes contributions and suggestions. Most contributions require you to agree to a | ||||||
| Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us | ||||||
| the rights to use your contribution. For details, visit https://cla.microsoft.com. | ||||||
|
|
||||||
| When you submit a pull request, a CLA-bot will automatically determine whether you need to provide | ||||||
| a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions | ||||||
| provided by the bot. You will only need to do this once across all repos using our CLA. | ||||||
|
|
||||||
| This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). | ||||||
| For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or | ||||||
| contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. | ||||||
|
|
||||||
| <!-- LINKS --> | ||||||
| [azure_cli]: https://docs.microsoft.com/cli/azure | ||||||
| [api_docs]: https://aka.ms/monitorexporterapidocs | ||||||
| [product_docs]: https://docs.microsoft.com/azure/azure-monitor/overview | ||||||
| [azure_portal]: https://portal.azure.com | ||||||
| [azure_sub]: https://azure.microsoft.com/free/ | ||||||
| [cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview | ||||||
| [cloud_shell_bash]: https://shell.azure.com/bash | ||||||
| [pip]: https://pypi.org/project/pip/ | ||||||
| [pypi]: https://pypi.org/project/opentelemetry-azure-monitor/ | ||||||
| [python]: https://www.python.org/downloads/ | ||||||
| [venv]: https://docs.python.org/3/library/venv.html | ||||||
| [virtualenv]: https://virtualenv.pypa.io | ||||||
| [ot_sdk_python]: https://github.com/open-telemetry/opentelemetry-python | ||||||
| [application_insights_namespace]: https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview#how-do-i-use-application-insights | ||||||
| [exporter_options]: https://opentelemetry-azure-monitor-python.readthedocs.io/en/latest/azure_monitor/export/export.options.html?highlight=options | ||||||
| [trace_concept]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#trace | ||||||
| [client_reference]: https://opentelemetry-azure-monitor-python.readthedocs.io/en/latest/azure_monitor/export/export.trace.html#module-azure_monitor.export.trace | ||||||
| [opentelemtry_spec]: https://opentelemetry.io/ | ||||||
| [instrumentation_library]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries | ||||||
| [tracer_provider]: https://opentelemetry-python.readthedocs.io/en/stable/api/trace.html?highlight=TracerProvider#opentelemetry.trace.TracerProvider | ||||||
| [span_processor]: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace.html?highlight=SpanProcessor# | ||||||
| [sampler_ref]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampling | ||||||
|
|
||||||
| [sample_authenticate_client_connstr]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py#L18 | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,52 +1,16 @@ | ||
| --- | ||
| page_type: sample | ||
| languages: | ||
| - python | ||
| products: | ||
| - microsoft-opentelemetry-exporter-azuremonitor | ||
| --- | ||
|
|
||
| # Microsoft Azure Monitor Opentelemetry Exporter Python Samples | ||
|
|
||
| These code samples show common champion scenario operations with the AzureMonitorSpanExporter. | ||
|
|
||
| * Trace: [sample_trace.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py) | ||
| * Client: [sample_client.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_client.py) | ||
| * Request: [sample_request.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_request.py) | ||
| * Server: [sample_server.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_server.py) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?