Observability

Optional OpenTelemetry tracing for the code-interpreter sandbox lifecycle.

Fully optional, with negligible overhead in the disabled path: every helper degrades to a no-op when OpenTelemetry is not installed, so gllm-tools takes no hard dependency on it. The host application owns telemetry setup (for example gl-observability's init_telemetry); this module only emits spans against whatever tracer provider the host has configured. Until a provider is configured OpenTelemetry hands back non-recording spans, so instrumentation stays cheap even when import succeeds.

Span names and attribute keys share the gl_sandbox.* namespace.

Usage

Decorate a sandbox method with @traced and record outcome-dependent attributes from inside the body; sandbox code never manages spans itself.

from gllm_tools.code_interpreter.observability import SpanAttr, SpanName, set_current_span_attributes, traced

@traced(SpanName.EXECUTE_CODE, **{SpanAttr.BACKEND: "e2b"})
async def execute_code(self, code, ...):
    set_current_span_attributes(**{SpanAttr.SANDBOX_ID: self.sandbox_id})
    ...
    set_current_span_attributes(**{SpanAttr.STATUS: status.value})

`SpanAttr`

Semantic attribute keys for code-interpreter spans (gl_sandbox.*).

Only low-cardinality metadata belongs here: never user code, command strings, or file contents. Those carry secrets and PII and would blow up span cardinality; record sizes and identifiers instead.

`SpanName`

Span names for the code-interpreter sandbox lifecycle.

`set_current_span_attributes(**attrs)`

Set attributes on the currently active span.

Used inside a @traced method to record outcome-dependent metadata without holding a span reference. No-op when tracing is unavailable or no span is recording.

Parameters:

Name	Type	Description	Default
`**attrs`	`Any`	Attributes to set. `None` values are skipped.	`{}`

`traced(name, **static_attrs)`

Wrap a sync or async method in a span named name.

Opens name as the current span for the call, applies static_attrs, and records a raised exception as a span error (the OpenTelemetry default). Set outcome-dependent attributes (status, sandbox id, sizes) from inside the body via set_current_span_attributes. No-op when tracing is unavailable.

Parameters:

Name	Type	Description	Default
`name`	`str`	Span name, e.g. `SpanName.EXECUTE_CODE`.	required
`**static_attrs`	`Any`	Attributes known at decoration time. `None` values are skipped.	`{}`

Returns:

Name	Type	Description
`Callable`	`Callable`	A decorator that wraps the target method.