Skip to main content
OpenTelemetry metrics instrumentation for Mellea. Provides metrics collection using OpenTelemetry Metrics API with support for:
  • Counters: Monotonically increasing values (e.g., request counts, token usage)
  • Histograms: Value distributions (e.g., latency, token counts)
  • UpDownCounters: Values that can increase or decrease (e.g., active sessions)
Metrics Exporters:
  • Console: Print metrics to console for debugging
  • OTLP: Export to OpenTelemetry Protocol collectors (Jaeger, Grafana, etc.)
  • Prometheus: Register metrics with prometheus_client registry for scraping
Configuration via environment variables: General:
  • MELLEA_METRICS_ENABLED: Enable/disable metrics collection (default: false)
  • OTEL_SERVICE_NAME: Service name for metrics (default: mellea)
Console Exporter (debugging):
  • MELLEA_METRICS_CONSOLE: Print metrics to console (default: false)
OTLP Exporter (production observability):
  • MELLEA_METRICS_OTLP: Enable OTLP metrics exporter (default: false)
  • OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for all signals (optional)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: Metrics-specific endpoint (optional, overrides general)
  • OTEL_METRIC_EXPORT_INTERVAL: Export interval in milliseconds (default: 60000)
Prometheus Exporter:
  • MELLEA_METRICS_PROMETHEUS: Enable Prometheus metric reader (default: false)
Multiple exporters can be enabled simultaneously. Example - Console debugging: export MELLEA_METRICS_ENABLED=true export MELLEA_METRICS_CONSOLE=true Example - OTLP production: export MELLEA_METRICS_ENABLED=true export MELLEA_METRICS_OTLP=true export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 Example - Prometheus monitoring: export MELLEA_METRICS_ENABLED=true export MELLEA_METRICS_PROMETHEUS=true Example - Multiple exporters: export MELLEA_METRICS_ENABLED=true export MELLEA_METRICS_CONSOLE=true export MELLEA_METRICS_OTLP=true export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 export MELLEA_METRICS_PROMETHEUS=true Programmatic usage: from mellea.telemetry.metrics import create_counter, create_histogram request_counter = create_counter( “mellea.requests”, description=“Total number of LLM requests”, unit=“1” ) request_counter.add(1, {“backend”: “ollama”, “model”: “llama2”}) latency_histogram = create_histogram( “mellea.request.duration”, description=“Request latency distribution”, unit=“ms” ) latency_histogram.record(150.5, {“backend”: “ollama”})

​
Functions

​
FUNC create_counter 

create_counter(name: str, description: str = '', unit: str = '1') -> Any
Create a counter instrument for monotonically increasing values. Counters are used for values that only increase, such as:
  • Total number of requests
  • Total tokens processed
  • Total errors encountered
Args:
  • name: Metric name (e.g., “mellea.requests.total”)
  • description: Human-readable description of what this metric measures
  • unit: Unit of measurement (e.g., “1” for count, “ms” for milliseconds)
Returns:
  • Counter instrument (or no-op if metrics disabled)

​
FUNC create_histogram 

create_histogram(name: str, description: str = '', unit: str = '1') -> Any
Create a histogram instrument for recording value distributions. Histograms are used for values that vary and need statistical analysis:
  • Request latency
  • Token counts per request
  • Response sizes
Args:
  • name: Metric name (e.g., “mellea.request.duration”)
  • description: Human-readable description
  • unit: Unit of measurement (e.g., “ms”, “tokens”, “bytes”)
Returns:
  • Histogram instrument (or no-op if metrics disabled)

​
FUNC create_up_down_counter 

create_up_down_counter(name: str, description: str = '', unit: str = '1') -> Any
Create an up-down counter for values that can increase or decrease. UpDownCounters are used for values that go up and down:
  • Active sessions
  • Items in a queue
  • Memory usage
Args:
  • name: Metric name (e.g., “mellea.sessions.active”)
  • description: Human-readable description
  • unit: Unit of measurement
Returns:
  • UpDownCounter instrument (or no-op if metrics disabled)

​
FUNC is_metrics_enabled 

is_metrics_enabled() -> bool
Check if metrics collection is enabled. Returns:
  • True if metrics are enabled, False otherwise

​
FUNC record_token_usage_metrics 

record_token_usage_metrics(input_tokens: int | None, output_tokens: int | None, model: str, backend: str, system: str) -> None
Record token usage metrics following Gen-AI semantic conventions. This is a no-op when metrics are disabled, ensuring zero overhead. Args:
  • input_tokens: Number of input tokens (prompt tokens), or None if unavailable
  • output_tokens: Number of output tokens (completion tokens), or None if unavailable
  • model: Model identifier (e.g., “gpt-4”, “llama2:7b”)
  • backend: Backend class name (e.g., “OpenAIBackend”, “OllamaBackend”)
  • system: Gen-AI system name (e.g., “openai”, “ollama”, “watsonx”)