mellea.telemetry.tracing

OpenTelemetry tracing instrumentation for Mellea.

OpenTelemetry tracing instrumentation for Mellea.

This module provides two independent trace scopes:

1. Application Trace (mellea.application) - User-facing operations
2. Backend Trace (mellea.backend) - LLM backend interactions

Follows OpenTelemetry Gen-AI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/

Configuration via environment variables:

• MELLEA_TRACE_APPLICATION: Enable/disable application tracing (default: false)
• MELLEA_TRACE_BACKEND: Enable/disable backend tracing (default: false)
• MELLEA_TRACE_CONTENT: Capture prompt/response content in spans (default: false). Content may include PII — enable only in controlled environments. Also recognised: OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (OTel standard).
• OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
• OTEL_SERVICE_NAME: Service name for traces (default: mellea)

Functions

FUNC is_application_tracing_enabled

is_application_tracing_enabled() -> bool

Check if application tracing is enabled.

Returns:

• True if application tracing has been enabled via the
• MELLEA_TRACE_APPLICATION environment variable.

FUNC is_backend_tracing_enabled

is_backend_tracing_enabled() -> bool

Check if backend tracing is enabled.

Returns:

• True if backend tracing has been enabled via the
• MELLEA_TRACE_BACKEND environment variable.

FUNC is_content_tracing_enabled

is_content_tracing_enabled() -> bool

Check if content capture is enabled.

Content capture records prompt and response text on spans and may contain PII. Enable only in controlled environments.

Returns:

• True if enabled via MELLEA_TRACE_CONTENT or
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.

FUNC add_span_event

add_span_event(span: Any, name: str, attributes: dict[str, Any] | None = None) -> None

Add a named event to a span if the span is not None.

Args:

• span: The span object (may be None if tracing is disabled).
• name: Event name.
• attributes: Optional event attributes.

FUNC trace_application

trace_application(name: str, **attributes: Any) -> Generator[Any, None, None]

Create an application trace span if application tracing is enabled.

Args:

• name: Name of the span.
• **attributes: Additional attributes to add to the span.

FUNC trace_backend

trace_backend(name: str, **attributes: Any) -> Generator[Any, None, None]

Create a backend trace span if backend tracing is enabled.

Follows Gen-AI semantic conventions for LLM operations.

Args:

• name: Name of the span.
• **attributes: Additional attributes to add to the span.

FUNC start_backend_span

start_backend_span(name: str, **attributes: Any) -> Any

Start a backend trace span without auto-closing (for async operations).

Use this when you need to manually control span lifecycle, such as for async operations where the span should remain open until post-processing.

Args:

• name: Name of the span
• **attributes: Additional attributes to add to the span

Returns:

• The span object if tracing is enabled, otherwise None

FUNC end_backend_span

end_backend_span(span: Any) -> None

End a backend trace span.

Args:

• span: The span object to end

FUNC set_span_attribute

set_span_attribute(span: Any, key: str, value: Any) -> None

Set an attribute on a span if the span is not None.

Args:

• span: The span object (may be None if tracing is disabled)
• key: Attribute key
• value: Attribute value

FUNC set_span_error

set_span_error(span: Any, exception: Exception) -> None

Record an exception on a span if the span is not None.

Args:

• span: The span object (may be None if tracing is disabled)
• exception: The exception to record

FUNC set_span_status_error

set_span_status_error(span: Any, description: str) -> None

Mark a span as ERROR without recording a phantom exception event.

Use this for validation failures and other non-exception error conditions where the span should be marked failed but no exception was actually raised. Calling set_span_error in these cases would create a misleading recorded exception event in OTEL traces.

Args:

• span: The span object (may be None if tracing is disabled)
• description: Human-readable reason for the failure.