Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mellea.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

VariableDescriptionDefault
OTEL_SERVICE_NAMEService name for all telemetry signalsmellea
OTEL_EXPORTER_OTLP_ENDPOINTOTLP endpoint for all telemetry signalsnone

​
Tracing variables

VariableDescriptionDefault
MELLEA_TRACE_APPLICATIONEnable application-level tracingfalse
MELLEA_TRACE_BACKENDEnable backend-level tracingfalse
MELLEA_TRACE_CONSOLEPrint traces to console (debugging)false

​
Metrics variables

VariableDescriptionDefault
MELLEA_METRICS_ENABLEDEnable metrics collectionfalse
MELLEA_METRICS_CONSOLEPrint metrics to console (debugging)false
MELLEA_METRICS_OTLPEnable OTLP metrics exporterfalse
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMetrics-specific OTLP endpoint (overrides general)none
MELLEA_METRICS_PROMETHEUSEnable Prometheus metric readerfalse
OTEL_METRIC_EXPORT_INTERVALExport interval in milliseconds60000
MELLEA_PRICING_FILEPath to a JSON file with custom model pricing overridesnone

​
Logging variables

VariableDescriptionDefault
MELLEA_LOGS_OTLPEnable OTLP logs exporterfalse
OTEL_EXPORTER_OTLP_LOG_ENDPOINTLogs-specific OTLP endpoint (overrides general)none

​
Quick start

Enable tracing and metrics with console output to verify everything works: 
export MELLEA_TRACE_APPLICATION=true
export MELLEA_TRACE_BACKEND=true
export MELLEA_TRACE_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_application_tracing_enabled,
    is_backend_tracing_enabled,
    is_metrics_enabled,
)

print(f"Application tracing: {is_application_tracing_enabled()}")
print(f"Backend tracing:     {is_backend_tracing_enabled()}")
print(f"Metrics:             {is_metrics_enabled()}")

​
Tracing

Mellea has two independent 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 both for full observability, or pick one depending on what you need to debug. When both scopes are active, backend spans nest inside application spans: 
session_context          (mellea.application)
├── aact                 (mellea.application)
│   ├── chat             (mellea.backend) [gen_ai.system=ollama]
│   └── requirement_validation  (mellea.application)
└── aact                 (mellea.application)
    └── chat             (mellea.backend) [gen_ai.system=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 counters — mellea.llm.tokens.input and mellea.llm.tokens.output after each LLM call.
  • Latency histograms — mellea.llm.request.duration (every request) and mellea.llm.ttfb (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.