Telemetry

Prerequisites: Quick Start complete, pip install "mellea[telemetry]", Ollama running locally.

Mellea provides built-in OpenTelemetry instrumentation across three independent pillars — tracing, metrics, and logging. Each can be enabled separately. All telemetry is opt-in: if the [telemetry] extra is not installed, every telemetry call is a silent no-op.

Note: OpenTelemetry is an optional dependency. Mellea works normally without it. Install with pip install "mellea[telemetry]" or uv pip install "mellea[telemetry]".

Configuration

All telemetry is configured via environment variables:

General

Variable	Description	Default
OTEL_SERVICE_NAME	Service name for all telemetry signals	mellea
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP endpoint for all telemetry signals	none

Tracing variables

Variable	Description	Default
MELLEA_TRACES_ENABLED	Enable tracing (umbrella flag)	false
MELLEA_TRACES_OTLP	Enable OTLP span exporter	false
MELLEA_TRACES_CONSOLE	Print traces to console (debugging)	false
MELLEA_TRACES_CONTENT	Capture prompt/response content on spans (may include PII)	false
MELLEA_GENERATION_CHUNK_EVENTS	Emit a chunk_processed event per streamed chunk (adds per-chunk span events and populates the time_per_output_chunk metric)	false
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Trace-specific OTLP endpoint (overrides general)	none

Metrics variables

Variable	Description	Default
MELLEA_METRICS_ENABLED	Enable metrics collection	false
MELLEA_METRICS_CONSOLE	Print metrics to console (debugging)	false
MELLEA_METRICS_OTLP	Enable OTLP metrics exporter	false
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Metrics-specific OTLP endpoint (overrides general)	none
MELLEA_METRICS_PROMETHEUS	Enable Prometheus metric reader	false
OTEL_METRIC_EXPORT_INTERVAL	Export interval in milliseconds	60000
MELLEA_PRICING_FILE	Path to a JSON file with custom model pricing overrides	none

Logging variables

Variable	Description	Default
MELLEA_LOGS_OTLP	Enable OTLP logs exporter	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Logs-specific OTLP endpoint (overrides general)	none

Quick start

Enable tracing and metrics with console output to verify everything works:

export MELLEA_TRACES_ENABLED=true
export MELLEA_TRACES_CONSOLE=true
export MELLEA_METRICS_ENABLED=true
export MELLEA_METRICS_CONSOLE=true
python your_script.py

Traces and metrics print to stdout. For production use, replace the console exporters with an OTLP endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=my-mellea-app

Checking telemetry status programmatically

from mellea.telemetry import is_metrics_enabled, is_tracing_enabled

print(f"Tracing: {is_tracing_enabled()}")
print(f"Metrics: {is_metrics_enabled()}")

Tracing

Mellea has two trace scopes:

• mellea.application — user-facing operations: session lifecycle, @generative calls, instruct() and act(), sampling strategies, and requirement validation.
• mellea.backend — LLM backend interactions following the OpenTelemetry Gen-AI Semantic Conventions. Records model calls, token usage, finish reasons, and API latency.

Enable tracing for full observability. Backend spans nest inside application spans:

session                  (mellea.application)
├── action               (mellea.application)
│   ├── chat             (mellea.backend) [gen_ai.provider.name=ollama]
│   └── validation       (mellea.application)
└── action               (mellea.application)
    └── chat             (mellea.backend) [gen_ai.provider.name=openai]

See Tracing for span attributes, exporter configuration (Jaeger, Grafana Tempo, etc.), and debugging guidance.

Metrics

Mellea automatically records the following metrics across all backends using OpenTelemetry. No code changes are required:

• Token usage histogram — gen_ai.client.token.usage after each LLM call, with input and output split by the gen_ai.token.type attribute.
• Latency histograms — mellea.llm.request.duration (every request) and gen_ai.client.operation.time_to_first_chunk (streaming requests only).
• Error counter — mellea.llm.errors on each failed backend call, classified by semantic error type.
• Cost counter — mellea.llm.cost.usd estimated request cost in USD, when pricing data is available for the model.
• Sampling counters — mellea.sampling.attempts, mellea.sampling.successes, and mellea.sampling.failures per strategy.
• Requirement counters — mellea.requirement.checks and mellea.requirement.failures per requirement type.
• Tool counter — mellea.tool.calls by tool name and status.

The metrics API also exposes create_counter, create_histogram, and create_up_down_counter for instrumenting your own application code.

Mellea supports three exporters that can run simultaneously:

• Console — print to stdout for debugging
• OTLP — export to production observability platforms
• Prometheus — register with prometheus_client for scraping

See Metrics for the full list of metrics, backend support matrix, exporter setup, custom instruments, and troubleshooting.

Logging

Mellea uses a color-coded console logger (MelleaLogger) by default. When the [telemetry] extra is installed and MELLEA_LOGS_OTLP=true is set, Mellea also exports logs to an OTLP collector alongside existing console output.

See Logging for console logging configuration, OTLP log export setup, and programmatic access via get_otlp_log_handler().

Full example: docs/examples/telemetry/telemetry_example.py

---

See also:

• Tracing — distributed traces with Gen-AI semantic conventions.
• Metrics — metrics, exporters, and custom instruments.
• Logging — console logging and OTLP log export.