Azure Core OpenTelemetry Tracing Plugin

1.0.0b12 · active · verified Thu Apr 09

This library provides an OpenTelemetry plugin for `azure-core`, enabling automatic distributed tracing for Python Azure SDK client library calls. It integrates with your OpenTelemetry setup to propagate context and create spans for Azure service interactions. The current version is `1.0.0b12`, indicating a beta release, and it is actively maintained as part of the broader Azure SDK for Python.

Warnings

gotcha This package only provides the OpenTelemetry plugin for Azure Core. Users are responsible for explicitly setting up the OpenTelemetry SDK (TracerProvider, SpanProcessor, Exporter) separately. Forgetting this step will result in no traces being generated.
Fix: Ensure `opentelemetry.trace.set_tracer_provider()` is called and at least one `SpanProcessor` is added to the `TracerProvider` before initializing Azure SDK clients.
gotcha The OpenTelemetry plugin must be explicitly enabled using `use_opentelemetry()` or by manually setting `azure.core.settings.settings.tracing_implementation` and `azure.core.settings.settings.tracing_manager` early in your application's lifecycle, before any Azure SDK clients are instantiated.
Fix: Call `from azure.core.tracing.ext.opentelemetry_span import use_opentelemetry; use_opentelemetry()` at the very beginning of your application code.
breaking As a beta release (`1.0.0b12`), the API or internal behavior of this library may change in future versions, potentially introducing breaking changes before a stable `1.0.0` release.
Fix: Monitor release notes carefully for future beta and stable versions. Pin to specific beta versions if stability is critical for your current development phase.
gotcha This library has strict dependency requirements on `opentelemetry-api` and `opentelemetry-sdk` versions (e.g., `>=1.15.0, <2.0.0`). Incompatible versions of the OpenTelemetry SDK can lead to runtime errors or tracing failures.
Fix: Always install the required OpenTelemetry packages alongside this library (`pip install azure-core-tracing-opentelemetry opentelemetry-sdk`) to ensure compatible versions are pulled in. Avoid manual installation of incompatible OpenTelemetry versions.

Install

pip install azure-core-tracing-opentelemetry opentelemetry-sdk opentelemetry-exporter-azure-monitor Install with Azure Monitor exporter
pip install azure-core-tracing-opentelemetry opentelemetry-sdk Install core tracing plugin

Imports

use_opentelemetry
```
from azure.core.tracing.ext.opentelemetry_span import use_opentelemetry
```
This function simplifies enabling OpenTelemetry tracing for Azure SDK clients.
OpenTelemetrySpan
```
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
```
The `OpenTelemetrySpan` class is located under the `ext` submodule.

Quickstart

This quickstart demonstrates how to set up OpenTelemetry tracing for Azure SDK operations. It configures a simple console exporter, enables the `azure-core` OpenTelemetry plugin, and then performs a basic Azure Blob Storage operation. Traces for the Blob Storage client calls will be output to the console.

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from azure.core.tracing.ext.opentelemetry_span import use_opentelemetry
from azure.storage.blob import BlobServiceClient

# 1. Set up OpenTelemetry TracerProvider and SpanProcessor
# This example uses ConsoleSpanExporter; for Azure Monitor, use AzureMonitorTraceExporter
trace.set_tracer_provider(TracerProvider())
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
trace.get_tracer_provider().add_span_processor(span_processor)

# 2. Enable OpenTelemetry tracing plugin for Azure SDK
use_opentelemetry()

# 3. Create an Azure SDK client (e.g., Azure Blob Storage)
# Ensure AZURE_STORAGE_CONNECTION_STRING is set in your environment for actual operations
connection_string = os.environ.get(
    "AZURE_STORAGE_CONNECTION_STRING",
    "DefaultEndpointsProtocol=https;AccountName=test;AccountKey=test;BlobEndpoint=https://test.blob.core.windows.net/"
)
if connection_string == "DefaultEndpointsProtocol=https;AccountName=test;AccountKey=test;BlobEndpoint=https://test.blob.core.windows.net/":
    print("WARNING: Using a placeholder connection string. Tracing will run, but actual Azure operations will fail unless AZURE_STORAGE_CONNECTION_STRING is set.")

blob_service_client = BlobServiceClient.from_connection_string(connection_string)

# 4. Perform an Azure SDK operation
try:
    container_name = "otel-test-container"
    container_client = blob_service_client.get_container_client(container_name)
    print(f"Attempting to create container '{container_name}'...")
    container_client.create_container()
    print(f"Container '{container_name}' created successfully.")
    print(f"Attempting to delete container '{container_name}'...")
    container_client.delete_container()
    print(f"Container '{container_name}' deleted successfully.")
except Exception as e:
    print(f"An error occurred during Azure Storage operation (check your connection string and permissions): {e}")

print("Traces should be printed to the console if successful and the connection string is valid.")

view raw JSON →