Skip to main content

OpenTelemetry instrumentation for Mellea.

This package provides observability capabilities for Mellea through OpenTelemetry, enabling tracing, metrics, and logging for both application-level operations and backend LLM interactions.

Package Structure:

  • tracing: Distributed tracing with two independent scopes:
    • Application traces (mellea.application): User-facing operations
    • Backend traces (mellea.backend): LLM backend interactions
  • metrics: Metrics collection for counters, histograms, and up-down counters
  • logging: Log export via OTLP
  • backend_instrumentation: Automatic instrumentation for backend operations

Configuration: All telemetry features are opt-in via environment variables:

Tracing:

  • MELLEA_TRACE_APPLICATION: Enable application tracing (default: false)
  • MELLEA_TRACE_BACKEND: Enable backend tracing (default: false)
  • OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
  • OTEL_SERVICE_NAME: Service name for traces (default: mellea)

Metrics:

  • MELLEA_METRICS_ENABLED: Enable metrics collection (default: false)
  • MELLEA_METRICS_CONSOLE: Print metrics to console (default: false)
  • MELLEA_METRICS_OTLP: Enable OTLP metrics exporter (default: false)
  • MELLEA_METRICS_PROMETHEUS: Enable Prometheus metric reader (default: false)
  • OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for metric export (optional)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: Metrics-specific OTLP endpoint (optional)
  • OTEL_METRIC_EXPORT_INTERVAL: Export interval in milliseconds (default: 60000)
  • OTEL_SERVICE_NAME: Service name for metrics (default: mellea)
  • MELLEA_PRICING_FILE: Path to a JSON file with custom model pricing overrides (optional)

Logging:

  • MELLEA_LOGS_OTLP: Enable OTLP log export (default: false)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: Logs-specific endpoint (optional)
  • OTEL_EXPORTER_OTLP_ENDPOINT: General OTLP endpoint (fallback)
  • OTEL_SERVICE_NAME: Service name for logs (default: mellea)

Dependencies: OpenTelemetry packages are optional. If not installed, telemetry features are gracefully disabled. Install with: pip install mellea[telemetry]

Example: from mellea.telemetry import trace_application, create_counter, get_otlp_log_handler import logging

Trace application operations

@trace_application("my_operation") def my_function(): pass

Collect metrics

counter = create_counter("mellea.requests", unit="1") counter.add(1, {"backend": "ollama"})

Export logs via OTLP

logger = logging.getLogger("my_app") handler = get_otlp_log_handler() if handler: logger.addHandler(handler)