Give AlbumentationsX a star on GitHub — it powers this leaderboard

Star on GitHub

azure-monitor-opentelemetry-exporter

Microsoft Azure Monitor Opentelemetry Exporter Client Library for Python

Downloads: 0 (30 days)
View on PyPIGitHubOwner: Azure

Description

Microsoft OpenTelemetry exporter for Azure Monitor

The exporter for Azure Monitor allows Python applications to export data from the OpenTelemetry SDK to Azure Monitor. The exporter is intended for users who require advanced configuration or have more complicated telemetry needs that require all of distributed tracing, logging and metrics. If you have simpler configuration requirements, we recommend using the Azure Monitor OpenTelemetry Distro instead for a simpler one-line setup.

Prior to using this SDK, please read and understand Data Collection Basics, especially the section on telemetry types. OpenTelemetry terminology differs from Application Insights terminology so it is important to understand the way the telemetry types map to each other.

Source code | [Package (PyPi)][pypi] | [API reference documentation][api_docs] | [Product documentation][product_docs] | [Samples][exporter_samples] | Changelog

Getting started

Install the package

Install the Microsoft OpenTelemetry exporter for Azure Monitor with [pip][pip]:

pip install azure-monitor-opentelemetry-exporter --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 - [OpenTelemetry SDK for Python][ot_sdk_python]
  • Python 3.8 or later - [Install Python][python]

Instantiate the client

Interaction with Azure monitor exporter starts with an instance of the AzureMonitorTraceExporter class for distributed tracing, AzureMonitorLogExporter for logging and AzureMonitorMetricExporter for metrics. 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 (experimental)

NOTE: The logging signal for the AzureMonitorLogExporter is currently in an EXPERIMENTAL state. Possible breaking changes may ensue in the future.

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

Metrics

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Tracing

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = 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 the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.

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

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter()

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

Key concepts

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

  • [OpenTelemetry][opentelemetry_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 instrumentation. A library that enables OpenTelemetry observability for another library is called an instrumentation Library.

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

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

  • [Logger][logger]: Converts a LogRecord into a readable LogData, and will be pushed through the SDK to be exported.

  • [Logger Provider][logger_provider]: Provides a Logger for the given instrumentation library.

  • [LogRecordProcessor][log_record_processor]: Interface to hook the log record emitting action.

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

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

  • [Metric][metric_concept]: Metric refers to recording raw measurements with predefined aggregation and sets of attributes for a period in time.

  • [Measurement][measurement]: Represents a data point recorded at a point in time.

  • [Instrument][instrument]: Instruments are used to report Measurements.

  • [Meter][meter]: The Meter is responsible for creating Instruments.

  • [Meter Provider][meter_provider]: Provides a Meter for the given instrumentation library.

  • [Metric Reader][metric_reader]: An SDK implementation object that provides the common configurable aspects of the OpenTelemetry Metrics SDK such as collection, flushing and shutdown.

  • [AzureMonitorMetricExporter][metric_reference]: This is the class that is initialized to send metric related telemetry to Azure Monitor.

  • [Trace][trace_concept]: 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][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][tracer]: Responsible for creating Spans.

  • [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.

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

  • [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.

  • 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 whenever AzureMonitorTraceExporter is used.

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

Configuration

All configuration options can be passed through the constructors of exporters through kwargs. 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 to False.
  • 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 for [Azure Active Directory (AAD) authentication][aad_for_ai_docs]. Defaults to None. See [samples][exporter_samples] for examples. The credential will be automatically created from the APPLICATIONINSIGHTS_AUTHENTICATION_STRING environment variable if not explicitly passed in. See [documentation][aad_env_var_docs] for more.

Examples

Logging (experimental)

NOTE: The logging signal for the AzureMonitorLogExporter is 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:

Review the [OpenTelemetry Logging SDK][ot_logging_sdk] to learn how to use OpenTelemetry components to collect logs.

When integrating the AzureMonitorLogExporter, it's strongly advised to utilize a named logger rather than the root logger. This recommendation stems from the exporter's dependency on azure-core for constructing and dispatching requests. Since azure-core itself uses a Python logger, attaching the handler to the root logger would inadvertently capture and export these internal log messages as well. This triggers a recursive loop of logging and exporting, leading to an unnecessary proliferation of log data. To avoid this, configure a named logger for your application's logging needs or set up your logging handler to filter out logs originating from the SDK library.

Export Hello World Log

"""
An example to show an application using Opentelemetry