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.
The span's backend label comes from the class's _BACKEND, so a subclass
is labeled with its own name without touching its methods.
from gllm_tools.code_interpreter.observability import SpanAttr, SpanName, set_current_span_attributes, traced
@traced(SpanName.EXECUTE_CODE)
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. |
{}
|
traced(name, **static_attrs)
Wrap a sync or async method in a span named name.
Opens name as the current span for the call, labels it with the backend
of the class the method runs on, applies static_attrs, and records a
raised exception as a span error with its secrets masked. Set
outcome-dependent attributes (status, sandbox id, sizes) from inside the body
via set_current_span_attributes. No-op when tracing is unavailable.
The backend label is the _BACKEND of the method's first argument (self,
or cls for a classmethod), read at call time, so an inherited method is
labeled with the subclass's name. A sandbox whose _BACKEND is empty is
labeled with its class name. Classes without a _BACKEND pass the label in
static_attrs, which wins over the class's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Span name, e.g. |
required |
**static_attrs
|
Any
|
Attributes known at decoration time. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
Callable |
Callable
|
A decorator that wraps the target method. |