observability.telemetry

OpenTelemetry integration for orchestrator observability.

Provides TelemetryManager which wraps OTel span creation with a no-op fallback when observability is disabled. This module has zero overhead when disabled and no hard dependency on opentelemetry packages.

OpenTelemetry integration for orchestrator observability.

Provides TelemetryManager which wraps OTel span creation with a no-op fallback when observability is disabled. This module has zero overhead when disabled and no hard dependency on opentelemetry packages.

class NoOpSpan[source]

Bases: object

Span that records nothing. Used when observability is disabled.

set_attribute(key, value)[source]

No-op: discard a span attribute.

Parameters:

key (str)
value (Any)

Return type:

None

record_exception(exception)[source]

No-op: discard an exception record.

Parameters:: exception (Exception)
Return type:: None

is_recording()[source]

Return False, indicating the span is not active.

Return type:: bool

class TelemetryManager[source]

Bases: object

Manages OpenTelemetry tracing for orchestrator execution.

When observability.enabled=false (the default), all span creation returns NoOpSpan instances with zero overhead. When enabled, spans are emitted via the configured OTLP gRPC exporter.

enabled: Whether OTel tracing is active.

service_name: Service name for OTel resource.

endpoint: OTLP gRPC endpoint.

property enabled: bool: Whether OTel tracing is active.

span(name)[source]

Create a traced span. Returns NoOpSpan when disabled.

Parameters:: name (str) – Span name (e.g., “orchestrator.run”).
Yields:: A span object with set_attribute() and record_exception().
Return type:: Generator[NoOpSpan, None, None]

shutdown()[source]

Flush and shutdown the tracer provider.

Return type:: None

get_telemetry_manager()[source]

Get the global TelemetryManager instance.

Creates on first call. Returns cached instance on subsequent calls. Call reload_telemetry() after config changes.

Returns:: The global TelemetryManager.
Return type:: TelemetryManager

reload_telemetry()[source]

Shutdown existing manager and create a fresh one.

Use after changing observability config at runtime.

Returns:: A new TelemetryManager.
Return type:: TelemetryManager

reset_telemetry()[source]

Reset the global TelemetryManager singleton.

Shuts down any active provider and sets the singleton to None. Intended for test teardown to prevent cross-test pollution.

Return type:: None

Classes

class NoOpSpan[source]

Bases: object

Span that records nothing. Used when observability is disabled.

set_attribute(key, value)[source]

No-op: discard a span attribute.

Parameters:

key (str)
value (Any)

Return type:

None

record_exception(exception)[source]

No-op: discard an exception record.

Parameters:: exception (Exception)
Return type:: None

is_recording()[source]

Return False, indicating the span is not active.

Return type:: bool

class TelemetryManager[source]

Bases: object

Manages OpenTelemetry tracing for orchestrator execution.

When observability.enabled=false (the default), all span creation returns NoOpSpan instances with zero overhead. When enabled, spans are emitted via the configured OTLP gRPC exporter.

enabled: Whether OTel tracing is active.

service_name: Service name for OTel resource.

endpoint: OTLP gRPC endpoint.

property enabled: bool: Whether OTel tracing is active.

span(name)[source]

Create a traced span. Returns NoOpSpan when disabled.

Parameters:: name (str) – Span name (e.g., “orchestrator.run”).
Yields:: A span object with set_attribute() and record_exception().
Return type:: Generator[NoOpSpan, None, None]

shutdown()[source]

Flush and shutdown the tracer provider.

Return type:: None

Functions

get_telemetry_manager()[source]

Get the global TelemetryManager instance.

Creates on first call. Returns cached instance on subsequent calls. Call reload_telemetry() after config changes.

Returns:: The global TelemetryManager.
Return type:: TelemetryManager

reload_telemetry()[source]

Shutdown existing manager and create a fresh one.

Use after changing observability config at runtime.

Returns:: A new TelemetryManager.
Return type:: TelemetryManager

reset_telemetry()[source]

Reset the global TelemetryManager singleton.

Shuts down any active provider and sets the singleton to None. Intended for test teardown to prevent cross-test pollution.

Return type:: None