diff --git a/sdk/monitor/ci.yml b/sdk/monitor/ci.yml index 27a617dfdf30..38afb35ce915 100644 --- a/sdk/monitor/ci.yml +++ b/sdk/monitor/ci.yml @@ -31,5 +31,5 @@ extends: Artifacts: - name: azure_mgmt_monitor safeName: azuremgmtmonitor - - name: opentelemetry_exporter_azuremonitor - safeName: opentelemetryexporterazuremonitor + - name: microsoft_opentelemetry_exporter_azuremonitor + safeName: microsoftopentelemetryexporterazuremonitor diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md index 81bb27c7b27e..3bab9b6bdf43 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md @@ -1,13 +1,219 @@ -# Azure Opentelemetry Exporter for Monitor +# Microsoft Opentelemetry exporter for Azure Monitor + +[![Gitter chat](https://img.shields.io/gitter/room/Microsoft/azure-monitor-python)](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. + +* [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. + +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()) +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. + +```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=' +) +# 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() +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 + +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. + + +[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 diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md index 819526123286..700670fa3bbb 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md @@ -1,52 +1,16 @@ - -## Installation - -```sh -$ pip install opentelemetry-azure-monitor -``` - -## Run the Applications - -### Trace - -* Update the code in trace.py to use your `INSTRUMENTATION_KEY` - -* Run the sample - -```sh -$ # from this directory -$ python trace.py -``` - -### Request - -* Update the code in request.py to use your `INSTRUMENTATION_KEY` - -* Run the sample - -```sh -$ pip install opentelemetry-instrumentation-requests -$ # from this directory -$ python request.py -``` - -### Server - -* Update the code in server.py to use your `INSTRUMENTATION_KEY` - -* Run the sample - -```sh -$ pip install opentelemetry-instrumentation-requests -$ pip install opentelemetry-instrumentation-wsgi -$ # from this directory -$ python server.py -``` - -* Open http://localhost:8080/ - - -## Explore the data - -After running the applications, data would be available in [Azure]( -https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview#where-do-i-see-my-telemetry) +--- +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) diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/client.py b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_client.py similarity index 82% rename from sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/client.py rename to sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_client.py index ae7397fcb760..559e144078e9 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/client.py +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_client.py @@ -1,8 +1,5 @@ # Copyright (c) Microsoft Corporation. All rights reserved. # Licensed under the MIT License. -# pylint: disable=import-error -# pylint: disable=no-member -# pylint: disable=no-name-in-module import os import requests from opentelemetry import trace @@ -17,7 +14,7 @@ RequestsInstrumentor().instrument() span_processor = BatchExportSpanProcessor( AzureMonitorSpanExporter( - connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"] + connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) ) trace.get_tracer_provider().add_span_processor(span_processor) diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/request.py b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_request.py similarity index 92% rename from sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/request.py rename to sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_request.py index 59000e4ed5d3..456f13903557 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/request.py +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_request.py @@ -17,7 +17,7 @@ RequestsInstrumentor().instrument() span_processor = SimpleExportSpanProcessor( AzureMonitorSpanExporter( - connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"] + connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) ) trace.get_tracer_provider().add_span_processor(span_processor) diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/server.py b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_server.py similarity index 95% rename from sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/server.py rename to sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_server.py index 6bd1efa8bcd4..116b12518bf2 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/server.py +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_server.py @@ -20,7 +20,7 @@ tracer = trace.get_tracer(__name__) exporter = AzureMonitorSpanExporter( - connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"] + connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) # SpanExporter receives the spans and send them to the target location. diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/trace.py b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py similarity index 92% rename from sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/trace.py rename to sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py index 6c9a8ef44838..b7b8c6db0f89 100644 --- a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/trace.py +++ b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py @@ -15,7 +15,7 @@ def callback_function(envelope): exporter = AzureMonitorSpanExporter( - connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"] + connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) exporter.add_telemetry_processor(callback_function) diff --git a/sdk/monitor/tests.yml b/sdk/monitor/tests.yml index 793cca324592..bb4cbbf43e4e 100644 --- a/sdk/monitor/tests.yml +++ b/sdk/monitor/tests.yml @@ -5,7 +5,7 @@ jobs: parameters: ServiceDirectory: monitor TestTimeoutInMinutes: 300 - BuildTargetingString: opentelemetry-exporter-azuremonitor + BuildTargetingString: microsoft-opentelemetry-exporter-azuremonitor EnvVars: AZURE_SUBSCRIPTION_ID: $(azure-subscription-id) AZURE_TENANT_ID: $(aad-azure-sdk-test-tenant-id)