nat.observability.exporter.span_exporter#

Attributes#

`logger`
`InputSpanT`
`OutputSpanT`

Classes#

SpanExporter

Abstract base class for span exporters with processing pipeline support.

Module Contents#

logger#

InputSpanT#

OutputSpanT#

class SpanExporter( context_state: ContextState | None = None, span_prefix: str | None = None, )#

Bases: nat.observability.exporter.processing_exporter.ProcessingExporter[InputSpanT, OutputSpanT], nat.observability.mixin.serialize_mixin.SerializeMixin

Abstract base class for span exporters with processing pipeline support.

This class specializes ProcessingExporter for span-based telemetry export. It converts IntermediateStep events into Span objects and supports processing pipelines for span transformation before export.

The generic types work as follows: - InputSpanT: The type of spans that enter the processing pipeline (typically Span) - OutputSpanT: The type of spans after processing through the pipeline (e.g., OtelSpan)

Key Features: - Automatic span creation from IntermediateStep events - Span lifecycle management (start/end event tracking) - Processing pipeline support via ProcessingExporter - Metadata and attribute handling - Usage information tracking - Automatic isolation of mutable state for concurrent execution using descriptors

Inheritance Hierarchy: - BaseExporter: Core event subscription and lifecycle management + DescriptorIsolationMixin - ProcessingExporter: Adds processor pipeline functionality - SpanExporter: Specializes for span creation and export

Event Processing Flow: 1. IntermediateStep (START) → Create Span → Add to tracking 2. IntermediateStep (END) → Complete Span → Process through pipeline → Export

Parameters#

context_state: ContextState, optional
The context state to use for the exporter. Defaults to None.

span_prefix: str, optional
The prefix name to use for span attributes. If None the value of the NAT_SPAN_PREFIX environment variable is used. Defaults to "nat" if neither are defined.

_outstanding_spans: nat.observability.exporter.base_exporter.IsolatedAttribute[dict]#

_span_stack: nat.observability.exporter.base_exporter.IsolatedAttribute[dict]#

_metadata_stack: nat.observability.exporter.base_exporter.IsolatedAttribute[dict]#

_span_prefix = None#

abstractmethod export_processed(item: OutputSpanT) → None#

Async:

Export the processed span.

Args:: item (OutputSpanT): The processed span to export.

export( event: nat.data_models.intermediate_step.IntermediateStep, ) → None#

The main logic that reacts to each IntermediateStep.

Args:: event (IntermediateStep): The event to process.

_process_start_event( event: nat.data_models.intermediate_step.IntermediateStep, )#

Process the start event of an intermediate step.

Args:: event (IntermediateStep): The event to process.

_process_end_event( event: nat.data_models.intermediate_step.IntermediateStep, )#

Process the end event of an intermediate step.

Args:: event (IntermediateStep): The event to process.

_to_json_string(data: Any) → str#

Transform payload into a JSON string for span attributes.

Converts the input data to a JSON string representation that is always compatible with OTLP span attribute encoding. Raw dicts and nested structures can contain types (None, custom objects) that OTLP cannot encode, so the result is serialized to a JSON string for safety.

The normalization process: 1. Recursively processes nested structures (dicts, lists, tuples) 2. Converts Pydantic models via model_dump(mode=’json’, exclude_none=True) 3. Filters out None values from dicts 4. Extracts ‘value’ key if present in dict and not None 5. Falls back to str() for non-serializable objects

Returns:: A valid JSON string representation of the data.

async _cleanup()#: Clean up any remaining spans.