Skip to content

Observability

OpenTelemetry instrumentation helpers for gllm-pipeline.

This module provides OpenTelemetry tracing utilities for the gllm-pipeline library. It exposes a tracer singleton and semantic attribute/event constants for consistent observability across pipeline executions.

SpanAttributes

Semantic attribute keys for OpenTelemetry spans.

These constants define the attribute namespace used throughout gllm-pipeline instrumentation. All keys follow the gllm.* convention for consistency with OpenTelemetry semantic conventions.

Attributes are organized by scope: 1. Pipeline-level: Attributes describing the overall pipeline execution 2. Step-level: Attributes describing individual step characteristics 3. Execution context: Attributes about the runtime environment 4. State: Attributes describing input/output state shapes

Examples:

from gllm_pipeline.observability.tracing import get_tracer, SpanAttributes

tracer = get_tracer()
with tracer.start_as_current_span("pipeline.invoke.my_pipeline") as span:
    span.set_attribute(SpanAttributes.PIPELINE_NAME, "my_pipeline")
    span.set_attribute(SpanAttributes.PIPELINE_STEP_COUNT, 3)

SpanEvents

Semantic event names for OpenTelemetry spans.

These constants define the event namespace used throughout gllm-pipeline instrumentation. Events mark significant points in the execution lifecycle and provide structured logging within spans.

Events are organized by category: 1. Lifecycle: Step entry, exit, and error events 2. Cache: Cache hit/miss events for steps with caching 3. Retry: Retry attempt events for steps with retry policies 4. State: State update events when step modifies pipeline state 5. Condition: Condition evaluation events for conditional steps

Examples:

from gllm_pipeline.observability.tracing import get_tracer, SpanEvents

tracer = get_tracer()
with tracer.start_as_current_span("pipeline.step.my_step") as span:
    span.add_event(SpanEvents.STEP_ENTRY)
    # ... step execution ...
    span.add_event(SpanEvents.STEP_EXIT)

get_tracer()

Get the gllm-pipeline tracer singleton.

Returns a trace.Tracer instance for creating spans. The tracer is lazily initialized on first call and cached for subsequent calls using thread-safe double-checked locking.

When no TracerProvider is configured, this returns a no-op tracer with zero overhead. The tracer version is automatically determined from package metadata, defaulting to "0.0.0" if the package is not installed (e.g., during editable installs without metadata).

This function is thread-safe and uses double-checked locking to ensure that only one tracer instance is created even when called concurrently from multiple threads.

Examples:

from gllm_pipeline.observability.tracing import get_tracer

tracer = get_tracer()
with tracer.start_as_current_span("my_span") as span:
    span.set_attribute("key", "value")

Returns:

Type Description
Tracer

trace.Tracer: Tracer instance for the gllm-pipeline instrumentation.