Skip to content

refactor: rename tracing env vars to plural and align with OTel semconv #1046

@ajbozarth

Description

@ajbozarth

Background

Tracing env vars need an umbrella enable flag and don't honor the signal-specific OTel endpoint variable. Some attribute names predate the current OTel GenAI semconv.

Env var naming decision (plural MELLEA_TRACES_*)

The OTel standard partner variable is plural: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT. For internal consistency with that and with the existing MELLEA_METRICS_* vars, this issue uses plural MELLEA_TRACES_*.

This diverges from the logging pillar, which landed singular MELLEA_LOG_* in PR #907 (intentional at the time, lightly discussed). The cross-pillar inconsistency between MELLEA_METRICS_* (plural), MELLEA_LOG_* (singular), and MELLEA_TRACES_* (plural, this issue) is a real wart — a separate fix issue has been filed to address it. This issue does not block on that conversation.

Scope

Env vars — rename/consolidate:

Old New
MELLEA_TRACE_APPLICATION + MELLEA_TRACE_BACKEND MELLEA_TRACES_ENABLED (umbrella)
(implicit via endpoint) MELLEA_TRACES_OTLP (explicit toggle)
MELLEA_TRACE_CONSOLE MELLEA_TRACES_CONSOLE
MELLEA_TRACE_CONTENT (added by PR #1036) MELLEA_TRACES_CONTENT
— (not currently honored) OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (signal-specific endpoint)

Keep the old MELLEA_TRACE_* names working with a deprecation warning for one release. The OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT alias added by #1036 alongside MELLEA_TRACE_CONTENT stays (OTel standard).

Attributes — align to current semconv:

  • Replace gen_ai.system with gen_ai.provider.name (metrics already uses this; @planetf1's PR feat(telemetry): close five OTel GenAI semantic convention emission gaps (#1035) #1036 is already doing dual-emission — this issue completes it by removing the legacy name after the deprecation window).
  • Add mellea. prefix to application-span attributes that currently have bare names in stdlib/functional.py (e.g., action_type, has_requirements, strategy_type, has_format, tool_calls, num_generate_logs, sampling_success, response, response_length).

Init timing — switch to lazy init so env changes after import are respected, matching mellea/telemetry/logging.py's pattern. This removes the need for importlib.reload(mellea.telemetry.tracing) in tests.

Phase & dependencies

Phase 1 (foundation). Depends on #1045. Blocks Phase 2 and Phase 3 once finished. Likely lands in the same PR as #1045 and {{NEW-C}}.

Related

  • {{PILLAR-NAMING}} — separate fix proposal to reconcile pillar env var naming across all three telemetry pillars. Non-blocking.

Acceptance criteria

  • New MELLEA_TRACES_* env vars work; old MELLEA_TRACE_* names warn and continue working (one-release deprecation).
  • gen_ai.system replaced with gen_ai.provider.name everywhere (after feat(telemetry): close five OTel GenAI semantic convention emission gaps (#1035) #1036 lands dual-emission).
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT honored when set.
  • Tracing tests no longer need importlib.reload.
  • Docs (docs/docs/evaluation-and-observability/ / docs/dev/telemetry.md as applicable) updated.

Parent epic: #444

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions