> ## 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.

# mellea.telemetry.tracing

> OpenTelemetry tracing instrumentation for Mellea.

export const SidebarFix = () => <script dangerouslySetInnerHTML={{
  __html: `
        (function () {
          const INTERVAL_MS = 500;

          const upgradeSidebar = () => {
            const links = document.querySelectorAll('a[href^="#"]');

            links.forEach((link) => {
              if (link.dataset.badged === "true") return;

              const rawText = (link.textContent || "").trim();

              // ========== FUNC ==========
              if (rawText.startsWith("FUNC ")) {
                const label = rawText.replace(/^FUNC\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Make the whole link a single flex row & prevent wrapping
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(48, 100, 227, 0.20)";
                badge.style.color = "#1D4ED8";

                badge.textContent = "FUNC";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }

              // ========== CLASS ==========
              if (rawText.startsWith("CLASS ")) {
                const label = rawText.replace(/^CLASS\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Same flex / nowrap treatment for class links
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(74, 222, 128, 0.20)";
                badge.style.color = "#15803D";

                badge.textContent = "CLASS";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }
            });
          };

          upgradeSidebar();
          setInterval(upgradeSidebar, INTERVAL_MS);
        })();
      `
}} />;

<SidebarFix />

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/](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

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_application_tracing_enabled` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_backend_tracing_enabled` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_content_tracing_enabled` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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`.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `add_span_event` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `trace_application` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `trace_backend` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `start_backend_span` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `end_backend_span` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
end_backend_span(span: Any) -> None
```

End a backend trace span.

**Args:**

* `span`: The span object to end

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `set_span_attribute` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `set_span_error` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `set_span_status_error` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/telemetry/tracing.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />