Package: azure-monitor-opentelemetry-exporter
Microsoft OpenTelemetry exporter for Azure MonitorThe 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|ChangelogGetting startedInstall the packageInstall the Microsoft OpenTelemetry exporter for Azure Monitor withpip:pipinstallazure-monitor-opentelemetry-exporter--prePrerequisitesTo use this package, you must have:Azure subscription -Create a free accountAzure Monitor -How to use application insightsOpenTelemetry SDK -OpenTelemetry SDK for PythonPython 3.7 or later -Install PythonInstantiate the clientInteraction with Azure monitor exporter starts with an instance of theAzureMonitorTraceExporterclass for distributed tracing,AzureMonitorLogExporterfor logging andAzureMonitorMetricExporterfor metrics. You will need aconnection_stringto instantiate the object.
Please find the samples linked below for demonstration as to how to construct the exporter using a connection string.Logging (experimental)NOTE: The logging signal for theAzureMonitorLogExporteris currently in an EXPERIMENTAL state. Possible breaking changes may ensue in the future.fromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExporterexporter=AzureMonitorLogExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])Metricsfromazure.monitor.opentelemetry.exporterimportAzureMonitorMetricExporterexporter=AzureMonitorMetricExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])Tracingfromazure.monitor.opentelemetry.exporterimportAzureMonitorTraceExporterexporter=AzureMonitorTraceExporter(connection_string=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 theAPPLICATIONINSIGHTS_CONNECTION_STRINGenvironment variable.fromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExporterexporter=AzureMonitorLogExporter()fromazure.monitor.opentelemetry.exporterimportAzureMonitorMetricExporterexporter=AzureMonitorMetricExporter()fromazure.monitor.opentelemetry.exporterimportAzureMonitorTraceExporterexporter=AzureMonitorTraceExporter()Key conceptsSome 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.Logger: Converts aLogRecordinto a readableLogData, and will be pushed through the SDK to be exported.Logger Provider: Provides aLoggerfor the given instrumentation library.LogRecordProcessor: Interface to hook the log record emitting action.LoggingHandler: A handler class which writes logging records in OpenTelemetry format from the standard Pythonlogginglibrary.AzureMonitorLogExporter: This is the class that is initialized to send logging related telemetry to Azure Monitor.Metric:Metricrefers to recording raw measurements with predefined aggregation and sets of attributes for a period in time.Measurement: Represents a data point recorded at a point in time.Instrument: Instruments are used to reportMeasurements.Meter: TheMeteris responsible for creatingInstruments.Meter Provider: Provides aMeterfor the given instrumentation library.Metric Reader: An SDK implementation object that provides the common configurable aspects of the OpenTelemetry Metrics SDK such as collection, flushing and shutdown.AzureMonitorMetricExporter: This is the class that is initialized to send metric related telemetry to Azure Monitor.Trace: Trace refers to distributed tracing. A distributed trace is a set of events, triggered as a result of a single logical operation, consolidated across various components of an application. In particular, a Trace 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 aTrace. 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 creatingSpans.Tracer Provider: Provides aTracerfor use by the given instrumentation library.Span Processor: A span processor allows hooks for SDK'sSpanstart 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.ApplicationInsightsSampler: Application Insights specific sampler used for consistent sampling across Application Insights SDKs and OpenTelemetry-based SDKs sending data to Application Insights. This sampler MUST be used wheneverAzureMonitorTraceExporteris used.For more information about these resources, seeWhat is Azure Monitor?.ConfigurationAll configuration options can be passed through the constructors of exporters throughkwargs. Below is a list of configurable options.connection_string: The connection string used for your Application Insights resource.disable_offline_storage: Boolean value to determine whether to disable storing failed telemetry records for retry. Defaults toFalse.storage_directory: Storage directory in which to store retry files. Defaults to<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.credential: Token credential, such as ManagedIdentityCredential or ClientSecretCredential, used forAzure Active Directory (AAD) authentication. Defaults to None. Seesamplesfor examples.ExamplesLogging (experimental)NOTE: The logging signal for theAzureMonitorLogExporteris currently in an EXPERIMENTAL state. Possible breaking changes may ensue in the future.The following sections provide several code snippets covering some of the most common tasks, including:Exporting a log recordExporting correlated log recordExporting log record with custom propertiesExporting an exceptions log recordReview theOpenTelemetry Logging SDKto learn how to use OpenTelemetry components to collect logs.Export Hello World Log"""An example to show an application using Opentelemetry logging sdk. Logging calls to the standard Pythonlogging library are tracked and telemetry is exported to application insights with the AzureMonitorLogExporter."""importosimportloggingfromopentelemetry._logsimportset_logger_providerfromopentelemetry.sdk._logsimport(LoggerProvider,LoggingHandler,)fromopentelemetry.sdk._logs.exportimportBatchLogRecordProcessorfromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExporterlogger_provider=LoggerProvider()set_logger_provider(logger_provider)exporter=AzureMonitorLogExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))handler=LoggingHandler()# Attach LoggingHandler to root loggerlogging.getLogger().addHandler(handler)logging.getLogger().setLevel(logging.NOTSET)logger=logging.getLogger(__name__)logger.warning("Hello World!")# Telemetry records are flushed automatically upon application exit# If you would like to flush records manually yourself, you can call force_flush()logger_provider.force_flush()Export Correlated Log"""An example showing how to include context correlation information in logging telemetry."""importosimportloggingfromopentelemetryimporttracefromopentelemetry._logsimportset_logger_providerfromopentelemetry.sdk._logsimport(LoggerProvider,LoggingHandler,)fromopentelemetry.sdk._logs.exportimportBatchLogRecordProcessorfromopentelemetry.sdk.traceimportTracerProviderfromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExportertrace.set_tracer_provider(TracerProvider())tracer=trace.get_tracer(__name__)logger_provider=LoggerProvider()set_logger_provider(logger_provider)exporter=AzureMonitorLogExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))handler=LoggingHandler()# Attach LoggingHandler to root loggerlogging.getLogger().addHandler(handler)logging.getLogger().setLevel(logging.NOTSET)logger=logging.getLogger(__name__)logger.info("INFO: Outside of span")withtracer.start_as_current_span("foo"):logger.warning("WARNING: Inside of span")logger.error("ERROR: After span")Export Custom Properties Log"""An example showing how to add custom properties to logging telemetry."""importosimportloggingfromopentelemetry._logsimportset_logger_providerfromopentelemetry.sdk._logsimport(LoggerProvider,LoggingHandler,)fromopentelemetry.sdk._logs.exportimportBatchLogRecordProcessorfromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExporterlogger_provider=LoggerProvider()set_logger_provider(logger_provider)exporter=AzureMonitorLogExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))handler=LoggingHandler()# Attach LoggingHandler to root loggerlogging.getLogger().addHandler(handler)logging.getLogger().setLevel(logging.NOTSET)logger=logging.getLogger(__name__)# Custom propertieslogger.debug("DEBUG: Debug with properties",extra={"debug":"true"})Export Exceptions Log"""An example showing how to export exception telemetry using the AzureMonitorLogExporter."""importosimportloggingfromopentelemetry._logsimport(get_logger_provider,set_logger_provider,)fromopentelemetry.sdk._logsimport(LoggerProvider,LoggingHandler,)fromopentelemetry.sdk._logs.exportimportBatchLogRecordProcessorfromazure.monitor.opentelemetry.exporterimportAzureMonitorLogExporterset_logger_provider(LoggerProvider())exporter=AzureMonitorLogExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])get_logger_provider().add_log_record_processor(BatchLogRecordProcessor(exporter))# Attach LoggingHandler to namespaced loggerhandler=LoggingHandler()logger=logging.getLogger(__name__)logger.addHandler(handler)logger.setLevel(logging.NOTSET)# The following code will generate two pieces of exception telemetry# that are identical in naturetry:val=1/0print(val)exceptZeroDivisionError:logger.exception("Error: Division by zero")try:val=1/0print(val)exceptZeroDivisionError:logger.error("Error: Division by zero",stack_info=True,exc_info=True)MetricsThe following sections provide several code snippets covering some of the most common tasks, including:Using different metric instrumentsCustomizing outputted metrics with viewsRecording instruments with attributesReview theOpenTelemetry Metrics SDKto learn how to use OpenTelemetry components to collect metrics.Metric instrument usage"""An example to show an application using all instruments in the OpenTelemetry SDK. Metrics createdand recorded using the sdk are tracked and telemetry is exported to application insights with theAzureMonitorMetricsExporter."""importosfromtypingimportIterablefromopentelemetryimportmetricsfromopentelemetry.metricsimportCallbackOptions,Observationfromopentelemetry.sdk.metricsimportMeterProviderfromopentelemetry.sdk.metrics.exportimportPeriodicExportingMetricReaderfromazure.monitor.opentelemetry.exporterimportAzureMonitorMetricExporterexporter=AzureMonitorMetricExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])reader=PeriodicExportingMetricReader(exporter,export_interval_millis=5000)metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))# Create a namespaced metermeter=metrics.get_meter_provider().get_meter("sample")# Callback functions for observable instrumentsdefobservable_counter_func(options:CallbackOptions)->Iterable[Observation]:yieldObservation(1,{})defobservable_up_down_counter_func(options:CallbackOptions,)->Iterable[Observation]:yieldObservation(-10,{})defobservable_gauge_func(options:CallbackOptions)->Iterable[Observation]:yieldObservation(9,{})# Countercounter=meter.create_counter("counter")counter.add(1)# Async Counterobservable_counter=meter.create_observable_counter("observable_counter",[observable_counter_func])# UpDownCounterup_down_counter=meter.create_up_down_counter("up_down_counter")up_down_counter.add(1)up_down_counter.add(-5)# Async UpDownCounterobservable_up_down_counter=meter.create_observable_up_down_counter("observable_up_down_counter",[observable_up_down_counter_func])# Histogramhistogram=meter.create_histogram("histogram")histogram.record(99.9)# Async Gaugegauge=meter.create_observable_gauge("gauge",[observable_gauge_func])# Upon application exit, one last collection is made and telemetry records are# flushed automatically. # If you would like to flush records manually yourself,# you can call force_flush()meter_provider.force_flush()Metric custom views"""This example shows how to customize the metrics that are output by the SDK using Views. Metrics createdand recorded using the sdk are tracked and telemetry is exported to application insights with theAzureMonitorMetricsExporter."""importosfromopentelemetryimportmetricsfromopentelemetry.sdk.metricsimportCounter,MeterProviderfromopentelemetry.sdk.metrics.exportimportPeriodicExportingMetricReaderfromopentelemetry.sdk.metrics.viewimportViewfromazure.monitor.opentelemetry.exporterimportAzureMonitorMetricExporterexporter=AzureMonitorMetricExporter.from_connection_string(os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])# Create a view matching the counter instrument `my.counter`# and configure the new name `my.counter.total` for the result metrics streamchange_metric_name_view=View(instrument_type=Counter,instrument_name="my.counter",name="my.counter.total",)reader=PeriodicExportingMetricReader(exporter,export_interval_millis=5000)provider=MeterProvider(metric_readers=[reader,],views=[change_metric_name_view,],)metrics.set_meter_provider(provider)meter=metrics.get_meter_provider().get_meter("view-name-change")my_counter=meter.create_counter("my.counter")my_counter.add(100)More examples with the metricsViewsSDK can be foundhere.Metric record attributes"""An example to show an application using different attributes with instruments in the OpenTelemetry SDK.Metrics created and recorded using the sdk are tracked and telemetry is exported to application insightswith the AzureMonitorMetricsExporter."""importosfromopentelemetryimportmetricsfromopentelemetry.sdk.metricsimportMeterProviderfromopentelemetry.sdk.metrics.exportimportPeriodicExportingMetricReaderfromazure.monitor.opentelemetry.exporterimportAzureMonitorMetricExporterexporter=AzureMonitorMetricExporter.from_connection_string(os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])reader=PeriodicExportingMetricReader(exporter,export_interval_millis=5000)metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))attribute_set1={"key1":"val1"}attribute_set2={"key2":"val2"}large_attribute_set={}foriinrange(20):key="key{}".format(i)val="val{}".format(i)large_attribute_set[key]=valmeter=metrics.get_meter_provider().get_meter("sample")# Countercounter=meter.create_counter("attr1_counter")counter.add(1,attribute_set1)# Counter2counter2=meter.create_counter("attr2_counter")counter2.add(10,attribute_set1)counter2.add(30,attribute_set2)# Counter3counter3=meter.create_counter("large_attr_counter")counter3.add(100,attribute_set1)counter3.add(200,large_attribute_set)TracingThe following sections provide several code snippets covering some of the most common tasks, including:Exporting a custom spanUsing an instrumentation to track a libraryEnabling sampling to limit the amount of telemetry sentReview theOpenTelemetry Tracing SDKto learn how to use OpenTelemetry components to collect logs.Export Hello World Trace"""An example to show an application using Opentelemetry tracing api and sdk. Custom dependencies aretracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter."""importosfromopentelemetryimporttracefromopentelemetry.sdk.traceimportTracerProviderfromopentelemetry.sdk.trace.exportimportBatchSpanProcessorfromazure.monitor.opentelemetry.exporterimportAzureMonitorTraceExportertracer_provider=TracerProvider()trace.set_tracer_provider(tracer_provider)tracer=trace.get_tracer(__name__)# This is the exporter that sends data to Application Insightsexporter=AzureMonitorTraceExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])span_processor=BatchSpanProcessor(exporter)trace.get_tracer_provider().add_span_processor(span_processor)withtracer.start_as_current_span("hello"):print("Hello, World!")# Telemetry records are flushed automatically upon application exit# If you would like to flush records manually yourself, you can call force_flush()tracer_provider.force_flush()Instrumentation with requests libraryOpenTelemetry also supports several instrumentations which allows to instrument with third party libraries.For a list of instrumentations available in OpenTelemetry, visit the contribdocumentation.This example shows how to instrument with therequestslibrary.Install the requests instrumentation package using pip install opentelemetry-instrumentation-requests."""An example to show an application instrumented with the OpenTelemetry requests instrumentation.Calls made with the requests library will be automatically tracked and telemetry is exported toapplication insights with the AzureMonitorTraceExporter.See more info on the requests instrumentation here:https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests"""importosimportrequestsfromopentelemetryimporttracefromopentelemetry.instrumentation.requestsimportRequestsInstrumentorfromopentelemetry.sdk.traceimportTracerProviderfromopentelemetry.sdk.trace.exportimportBatchSpanProcessorfromazure.monitor.opentelemetry.exporterimportAzureMonitorTraceExporter# This line causes your calls made with the requests library to be tracked.RequestsInstrumentor().instrument()trace.set_tracer_provider(TracerProvider())tracer=trace.get_tracer(__name__)exporter=AzureMonitorTraceExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])span_processor=BatchSpanProcessor(exporter)trace.get_tracer_provider().add_span_processor(span_processor)# This request will be tracedresponse=requests.get(url="https://azure.microsoft.com/")Enabling samplingYou can enable sampling to limit the amount of telemetry records you receive. In order to enable correct sampling in Application Insights, use theApplicationInsightsSampleras shown below."""An example to show an application using the ApplicationInsightsSampler to enable sampling for your telemetry.Specify a sampling rate for the sampler to limit the amount of telemetry records you receive. Custom dependenciesare tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter."""importosfromopentelemetryimporttracefromopentelemetry.sdk.traceimportTracerProviderfromopentelemetry.sdk.trace.exportimportBatchSpanProcessorfromazure.monitor.opentelemetry.exporterimport(ApplicationInsightsSampler,AzureMonitorTraceExporter,)# Sampler expects a sample rate of between 0 and 1 inclusive# A rate of 0.75 means approximately 75% of your telemetry will be sentsampler=ApplicationInsightsSampler(0.75)trace.set_tracer_provider(TracerProvider(sampler=sampler))tracer=trace.get_tracer(__name__)exporter=AzureMonitorTraceExporter(connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"])span_processor=BatchSpanProcessor(exporter)trace.get_tracer_provider().add_span_processor(span_processor)foriinrange(100):# Approximately 25% of these spans should be sampled outwithtracer.start_as_current_span("hello"):print("Hello, World!")Flush/shutdown behaviorFor all applications set up with OpenTelemetry SDK and Azure Monitor exporters, telemetry is flushed automatically upon application exit. Note that this does not include when application ends abruptly or crashes due to uncaught exception.TroubleshootingThe exporter raises exceptions defined inAzure Core.Next stepsMore sample codePlease find further examples in thesamplesdirectory demonstrating common scenarios.Additional documentationFor more extensive documentation on the Azure Monitor service, see theAzure Monitor documentationon docs.microsoft.com.For detailed overview of OpenTelemetry, visit theiroverviewpage.For the official OpenTelemetry Python documentation and how to enable other telemetry scenarios, visit the official OpenTelemetrywebsite.For more information on the Azure Monitor OpenTelemetry Distro, which is a bundle of useful, pre-assembled components (one of them being this current package) that enable telemetry scenarios with Azure Monitor, visit theREADME.ContributingThis 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, visithttps://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 theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.