or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdlog-export.mdmetrics-export.mdtrace-export.md
tile.json

tessl/pypi-opencensus-ext-azure

OpenCensus Azure Monitor Exporter for telemetry data (logs, metrics, and traces) to Azure Monitor.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/opencensus-ext-azure@1.1.x

To install, run

npx @tessl/cli install tessl/pypi-opencensus-ext-azure@1.1.0

index.mddocs/

OpenCensus Azure Monitor Extension

OpenCensus Azure Monitor Extension provides comprehensive telemetry data export capabilities from OpenCensus instrumentation directly to Azure Monitor. The package enables Python applications to send logs, distributed traces, and metrics to Microsoft Azure Application Insights for monitoring, diagnostics, and performance analysis.

Package Information

  • Package Name: opencensus-ext-azure
  • Version: 1.1.15
  • Language: Python
  • Installation: pip install opencensus-ext-azure
  • License: Apache-2.0

Core Imports

Primary importers for the three main exporters:

from opencensus.ext.azure.log_exporter import AzureLogHandler, AzureEventHandler
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.ext.azure.metrics_exporter import MetricsExporter, new_metrics_exporter

Configuration and common utilities:

from opencensus.ext.azure.common import Options
from opencensus.ext.azure.common.storage import LocalFileStorage, LocalFileBlob
from opencensus.ext.azure.common.protocol import (
    BaseObject, Envelope, Data, DataPoint, Event, ExceptionData, 
    Message, MetricData, Request, RemoteDependency
)
from opencensus.ext.azure.common.transport import TransportMixin, TransportStatusCode
from opencensus.ext.azure.common.processor import ProcessorMixin
from opencensus.ext.azure.common.utils import (
    validate_instrumentation_key, parse_connection_string, 
    azure_monitor_context, timestamp_to_duration, timestamp_to_iso_str
)

Basic Usage

Quick Start - Logging

import logging
from opencensus.ext.azure.log_exporter import AzureLogHandler

# Configure the handler
handler = AzureLogHandler(connection_string="InstrumentationKey=your-key-here")
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.INFO)

# Use standard Python logging
logging.info("This message will be sent to Azure Monitor")
logging.error("This error will be tracked as an exception", exc_info=True)

Quick Start - Distributed Tracing

from opencensus.trace.tracer import Tracer
from opencensus.ext.azure.trace_exporter import AzureExporter

# Configure the exporter
exporter = AzureExporter(connection_string="InstrumentationKey=your-key-here")
tracer = Tracer(exporter=exporter)

# Create and use spans
with tracer.span(name="my_operation") as span:
    span.add_attribute("key", "value")
    # Your application logic here

Quick Start - Metrics

from opencensus.ext.azure.metrics_exporter import new_metrics_exporter

# Create a configured exporter with standard metrics
exporter = new_metrics_exporter(
    connection_string="InstrumentationKey=your-key-here",
    enable_standard_metrics=True
)

# Standard metrics (CPU, memory, requests) are automatically collected

Architecture

The OpenCensus Azure Monitor Extension follows a modular architecture:

  • Exporters: Core classes that handle telemetry data transformation and transmission to Azure Monitor
  • Transport Layer: HTTP communication with Azure Monitor endpoints, including retry logic and local storage
  • Storage Layer: Optional local file persistence for reliability during network issues
  • Processing Layer: Telemetry processors for data filtering and enrichment
  • Protocol Layer: Azure Monitor telemetry protocol implementation and data serialization

Each exporter inherits common functionality from mixins while providing specialized telemetry type handling.

Capabilities

Log Export

Python logging integration that sends log messages and exceptions to Azure Monitor as trace telemetry and custom events.

class AzureLogHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
    def __init__(self, **options): ...
    def emit(self, record): ...
    def close(self, timeout=None): ...
    def add_telemetry_processor(self, processor): ...

class AzureEventHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
    def __init__(self, **options): ...
    def emit(self, record): ...
    def close(self, timeout=None): ...
    def add_telemetry_processor(self, processor): ...

Log Export

Trace Export

Distributed tracing export that sends OpenCensus span data to Azure Monitor for request tracking, dependency mapping, and performance analysis.

class AzureExporter(BaseExporter, TransportMixin, ProcessorMixin):
    def __init__(self, **options): ...
    def export(self, span_datas): ...
    def span_data_to_envelope(self, span_data): ...
    def add_telemetry_processor(self, processor): ...

Trace Export

Metrics Export

Performance counters and custom metrics collection with automatic standard metrics for system monitoring.

class MetricsExporter(TransportMixin, ProcessorMixin):
    def __init__(self, is_stats=False, **options): ...
    def export_metrics(self, metrics): ...
    def metric_to_envelopes(self, metric): ...
    def shutdown(self): ...
    def add_telemetry_processor(self, processor): ...

def new_metrics_exporter(**options):
    """
    Factory function to create a fully configured metrics exporter.
    
    Args:
        **options: Configuration options for the exporter
        
    Returns:
        MetricsExporter: Configured exporter with background thread and standard metrics
    """

Metrics Export

Configuration and Common

Shared configuration options, utilities, protocol objects, and transport functionality used across all exporters.

class Options(BaseObject):
    def __init__(self, **options): ...
    
def process_options(options): ...
def parse_connection_string(connection_string): ...
def validate_instrumentation_key(instrumentation_key): ...

class LocalFileStorage:
    def __init__(self, path, **options): ...
    def put(self, data, lease_period=0): ...
    def get(self): ...
    def close(self): ...

class LocalFileBlob:
    def __init__(self, fullpath): ...
    def get(self): ...
    def put(self, data, lease_period=0): ...
    def delete(self): ...

class TransportMixin:
    def _transmit(self, envelopes): ...
    def _transmit_from_storage(self): ...

class ProcessorMixin:
    def add_telemetry_processor(self, processor): ...
    def apply_telemetry_processors(self, envelopes): ...

Configuration

Common Configuration Options

All exporters accept these configuration parameters:

  • connection_string (str): Azure Monitor connection string (recommended)
  • instrumentation_key (str): Instrumentation key (deprecated, use connection_string)
  • endpoint (str): Custom endpoint URL for Azure Monitor
  • export_interval (float): Export frequency in seconds (default: 15.0)
  • max_batch_size (int): Maximum batch size for telemetry (default: 100)
  • enable_local_storage (bool): Enable local file storage for reliability (default: True)
  • storage_path (str): Custom storage path for local files
  • timeout (float): Network timeout in seconds (default: 10.0)
  • proxies (dict): Proxy configuration for HTTP requests
  • credential: Azure credential object for authentication

Standard Metrics

When enabled, the metrics exporter automatically collects:

  • Process CPU Usage: Processor time consumption
  • Available Memory: System memory availability
  • Process Memory Usage: Application memory consumption
  • Request Rate: Incoming request frequency
  • Request Average Execution Time: Request processing duration

Error Handling

All exporters may raise:

  • ValueError: Invalid configuration options or parameters
  • Network exceptions: During telemetry transmission (handled with retry logic)
  • Storage exceptions: When local storage is enabled and encounters file system issues

Dependencies

  • opencensus >= 0.11.4, < 1.0.0
  • azure-core >= 1.12.0, < 2.0.0
  • azure-identity >= 1.5.0, < 2.0.0
  • psutil >= 5.6.3
  • requests >= 2.19.0