Microsoft Opentelemetry exporter for Azure Monitor Azure SDK for Python 2.0.0 documentation

The exporter for Azure Monitor allows you to export data utilizing the OpenTelemetry SDK and send telemetry data to Azure Monitor for applications written in Python. Source code | Package (PyPi) | API reference documentation | Product documentation | Samples | Changelog

Gitter chat

The exporter for Azure Monitor allows you to export data utilizing the OpenTelemetry SDK and send telemetry data to Azure Monitor for applications written in Python.

Source code | Package (PyPi) | API reference documentation | Product documentation | Samples | Changelog

Getting started

Install the package

Install the Microsoft Opentelemetry exporter for Azure Monitor with pip:

pip install azure-monitor-opentelemetry-exporter --pre

Prerequisites:

To use this package, you must have:

Instantiate the client

Interaction with Azure monitor exporter starts with an instance of the AzureMonitorTraceExporter class for distributed tracing or AzureMonitorTraceExporter for logging. You will need a connection_string to instantiate the object. Please find the samples linked below for demonstration as to how to construct the exporter using a connection string.

Logging

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter exporter = AzureMonitorLogExporter.from_connection_string( conn_str = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] )

Tracing

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter exporter = AzureMonitorTraceExporter.from_connection_string( conn_str = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] )

You can also instantiate the exporter directly via the constructor. In this case, the connection string will be automatically populated from the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter exporter = AzureMonitorLogExporter() 
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter exporter = AzureMonitorTraceExporter()

Key concepts

Some of the key concepts for the Azure monitor exporter include:

  • Opentelemetry: 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: The ability to call the opentelemetry API directly by any application is facilitated by instrumentation. A library that enables OpenTelemetry observability for another library is called an instrumentation Library.

  • Log: Log refers to capturing of logging, exception and events.

  • LogRecord: Represents a log record emitted from a supported logging library.

  • LogEmitter: Converts a LogRecord into a readable LogData, and will be pushed through the SDK to be exported.

  • LogEmitter Provider: Provides a LogEmitter for the given instrumentation library.

  • LogProcessor: Inteface to hook the log record emitting action.

  • LoggingHandler: A handler class which writes logging records in OpenTelemetry format from the standard Python logging library.

  • AzureMonitorLogExporter: This is the class that is initialized to send logging related telemetry to Azure Monitor.

  • Trace: 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.

  • Span: Represents a single operation within a Trace. Can be nested to form a trace tree. Each trace contains a root span, which typically describes the entire operation and, optionally, one ore more sub-spans for its sub-operations.

  • Tracer: Responsible for creating Spans.

  • Tracer Provider: Provides a Tracer for use by the given instrumentation library.

  • Span Processor: A span processor allows hooks for SDK’s Span start and end method invocations. Follow the link for more information.

  • AzureMonitorTraceExporter: This is the class that is initialized to send tracing related telemetry to Azure Monitor.

  • Sampling: 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.

For more information about these resources, see What is Azure Monitor?.

Examples

Logging

The following sections provide several code snippets covering some of the most common tasks, including:

Export Hello World Log

import os import logging from opentelemetry.sdk._logs import ( LogEmitterProvider, LoggingHandler, set_log_emitter_provider, ) from opentelemetry.sdk._logs.export import BatchLogProcessor from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter log_emitter_provider = LogEmitterProvider() set_log_emitter_provider(log_emitter_provider) exporter = AzureMonitorLogExporter.from_connection_string( os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) log_emitter_provider.add_log_processor(BatchLogProcessor(exporter)) handler = LoggingHandler() # Attach LoggingHandler to root logger logging.getLogger().addHandler(handler) logging.getLogger().setLevel(logging.NOTSET) logger = logging.getLogger(__name__) logger.warning("Hello World!")

Export Custom Properties Log

import os import logging from opentelemetry.sdk._logs import ( LogEmitterProvider, LoggingHandler, set_log_emitter_provider, ) from opentelemetry.sdk._logs.export import BatchLogProcessor from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter log_emitter_provider = LogEmitterProvider() set_log_emitter_provider(log_emitter_provider) exporter = AzureMonitorLogExporter.from_connection_string( os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"] ) log_emitter_provider.add_log_processor(BatchLogProcessor(exporter)) handler = LoggingHandler() # Attach LoggingHandler to root logger logging.getLogger().addHandler(handler) logging.getLogger().setLevel(logging.NOTSET) logger = logging.getLogger(__name__) # Custom properties logger.debug("DEBUG: Debug with properties", extra={"debug": "true"})

Tracing

The following sections provide several code snippets covering some of the most common tasks, including:

Export Hello World Trace

import os from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter exporter = AzureMonitorTraceExporter.from_connection_string( connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "] ) trace.set_tracer_provider(TracerProvider()) tracer = trace.get_tracer(__name__) span_processor = BatchSpanProcessor(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 library.

  • Install the requests integration package using pip install opentelemetry-instrumentation-requests.

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 BatchSpanProcessor from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter 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 = BatchSpanProcessor( AzureMonitorTraceExporter.from_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.

Next steps

More sample code

Please find further examples in the samples directory demonstrating common scenarios.

Additional documentation

For more extensive documentation on the Azure Monitor service, see the Azure Monitor documentation on docs.microsoft.com.

For detailed overview of Opentelemetry, visit their overview 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. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Indices and tables

Developer Documentation

ncG1vNJzZmiZqqq%2Fpr%2FDpJuom6Njr627wWeaqKqVY8SqusOorqxmnprBcHDWnploqKmptbC6jpqxrqqVYrqwusitpqtln6Wyr8DEpZymnaSnxm6x16mmq6yVp3xyeo9nZ5tuX567pbHXZ5%2BtpZw%3D

 Share!