nat.plugins.opentelemetry#

Submodules#

Classes#

`OtelSpanExporter`	Abstract base class for OpenTelemetry exporters.
`OTLPSpanAdapterExporter`	An OpenTelemetry OTLP span exporter for sending traces to OTLP-compatible services.
`OTLPSpanHeaderRedactionAdapterExporter`	An OpenTelemetry OTLP span exporter with built-in redaction and privacy tagging.

Package Contents#

class OtelSpanExporter( context_state: nat.builder.context.ContextState | None = None, batch_size: int = 100, flush_interval: float = 5.0, max_queue_size: int = 1000, drop_on_overflow: bool = False, shutdown_timeout: float = 10.0, resource_attributes: dict[str, str] | None = None, )#

Bases: nat.observability.exporter.span_exporter.SpanExporter[nat.data_models.span.Span, nat.plugins.opentelemetry.otel_span.OtelSpan]

Abstract base class for OpenTelemetry exporters.

This class provides a specialized implementation for OpenTelemetry exporters. It builds upon SpanExporter’s span construction logic and automatically adds a SpanToOtelProcessor to transform Span objects into OtelSpan objects.

The processing flow is: IntermediateStep → Span → OtelSpan → Export

Key Features: - Automatic span construction from IntermediateStep events (via SpanExporter) - Built-in Span to OtelSpan conversion (via SpanToOtelProcessor) - Support for additional processing steps if needed - Type-safe processing pipeline with enhanced TypeVar compatibility - Batching support for efficient export

Inheritance Hierarchy: - BaseExporter: Core functionality + TypeIntrospectionMixin - ProcessingExporter: Processor pipeline support - SpanExporter: Span creation and lifecycle management - OtelExporter: OpenTelemetry-specific span transformation

Generic Types: - InputSpanT: Always Span (from IntermediateStep conversion) - OutputSpanT: Always OtelSpan (for OpenTelemetry compatibility)

Initialize the OpenTelemetry exporter.

Args:: context_state: The context state to use for the exporter. batch_size: The batch size for exporting spans. flush_interval: The flush interval in seconds for exporting spans. max_queue_size: The maximum queue size for exporting spans. drop_on_overflow: Whether to drop spans on overflow. shutdown_timeout: The shutdown timeout in seconds. resource_attributes: Additional resource attributes for spans.

_resource#

async export_processed( item: nat.plugins.opentelemetry.otel_span.OtelSpan | list[nat.plugins.opentelemetry.otel_span.OtelSpan], ) → None#

Export the processed span(s).

This method handles the common logic for all OTEL exporters: - Normalizes single spans vs. batches - Sets resource attributes on spans - Delegates to the abstract export_otel_spans method

Args:

item (OtelSpan | list[OtelSpan]): The processed span(s) to export.: Can be a single span or a batch of spans from BatchingProcessor.

abstractmethod export_otel_spans( spans: list[nat.plugins.opentelemetry.otel_span.OtelSpan], ) → None#

Async:

Export a list of OpenTelemetry spans.

This method must be implemented by concrete exporters to handle the actual export logic (e.g., HTTP requests, file writes, etc.).

Args:: spans (list[OtelSpan]): The list of spans to export.

class OTLPSpanAdapterExporter(

*,

context_state: nat.builder.context.ContextState | None = None,

batch_size: int = 100,

flush_interval: float = 5.0,

max_queue_size: int = 1000,

drop_on_overflow: bool = False,

shutdown_timeout: float = 10.0,

resource_attributes: dict[str, str] | None = None,

endpoint: str,

headers: dict[str, str] | None = None,

**otlp_kwargs,

)#

Bases: nat.plugins.opentelemetry.mixin.otlp_span_exporter_mixin.OTLPSpanExporterMixin, nat.plugins.opentelemetry.otel_span_exporter.OtelSpanExporter

An OpenTelemetry OTLP span exporter for sending traces to OTLP-compatible services.

This class combines the OtelSpanExporter base functionality with OTLP-specific export capabilities to provide a complete solution for sending telemetry traces to any OTLP-compatible collector or service via HTTP.

Key Features: - Complete span processing pipeline (IntermediateStep → Span → OtelSpan → Export) - Batching support for efficient transmission - OTLP HTTP protocol for maximum compatibility - Configurable authentication via headers - Resource attribute management - Error handling and retry logic

This exporter is commonly used with services like: - OpenTelemetry Collector - Jaeger (OTLP endpoint) - Grafana Tempo - Custom OTLP-compatible backends

Example:

exporter = OTLPSpanAdapterExporter(
    endpoint="https://api.service.com/v1/traces",
    headers={"Authorization": "Bearer your-token"},
    batch_size=50,
    flush_interval=10.0
)

Initialize the OTLP span exporter.

Args:: context_state: The context state for the exporter. batch_size: Number of spans to batch before exporting. flush_interval: Time in seconds between automatic batch flushes. max_queue_size: Maximum number of spans to queue. drop_on_overflow: Whether to drop spans when queue is full. shutdown_timeout: Maximum time to wait for export completion during shutdown. resource_attributes: Additional resource attributes for spans. endpoint: The endpoint for the OTLP service. headers: The headers for the OTLP service. otlp_kwargs: Additional keyword arguments for the OTLP service.

class OTLPSpanHeaderRedactionAdapterExporter(

*,

context_state: nat.builder.context.ContextState | None = None,

batch_size: int = 100,

flush_interval: float = 5.0,

max_queue_size: int = 1000,

drop_on_overflow: bool = False,

shutdown_timeout: float = 10.0,

resource_attributes: dict[str, str] | None = None,

redaction_attributes: list[str] | None = None,

redaction_headers: list[str] | None = None,

redaction_callback: collections.abc.Callable[Ellipsis, Any] | None = None,

redaction_enabled: bool = False,

force_redaction: bool = False,

redaction_value: str = '[REDACTED]',

redaction_tag: str | None = None,

tags: collections.abc.Mapping[str, enum.Enum | str] | None = None,

endpoint: str,

headers: dict[str, str] | None = None,

**otlp_kwargs,

)#

Bases: nat.plugins.opentelemetry.otlp_span_adapter_exporter.OTLPSpanAdapterExporter

An OpenTelemetry OTLP span exporter with built-in redaction and privacy tagging.

This class extends OTLPSpanAdapterExporter to provide automatic span redaction and privacy tagging capabilities. It automatically adds header-based redaction and span tagging processors to the processing pipeline.

Key Features: - Header-based span redaction with configurable callback logic - Privacy level tagging for compliance and governance - Complete span processing pipeline (IntermediateStep → Span → Redaction → Tagging → OtelSpan → Batching → Export) - Batching support for efficient transmission - OTLP HTTP protocol for maximum compatibility - Configurable authentication via headers - Resource attribute management - Error handling and retry logic

The redaction processor allows conditional redaction based on authentication headers, while the tagging processor adds privacy-level metadata to spans for downstream processing and compliance tracking.

This exporter is commonly used with services like: - OpenTelemetry Collector - DataDog (OTLP endpoint) - Jaeger (OTLP endpoint) - Grafana Tempo - Custom OTLP-compatible backends

Example:

def should_redact(auth_key: str) -> bool:
    return auth_key in ["sensitive_user", "test_user"]

exporter = OTLPSpanRedactionAdapterExporter(
    endpoint="https://api.service.com/v1/traces",
    headers={"Authorization": "Bearer your-token"},
    redaction_attributes=["user.email", "request.body"],
    redaction_headers=["x-user-id"],
    redaction_callback=should_redact,
    redaction_value="REDACTED",
    tags={"privacy.level": PrivacyLevel.HIGH, "service.type": "sensitive"},
    batch_size=50,
    flush_interval=10.0
)

Initialize the OTLP span exporter with redaction and tagging capabilities.

Args:: context_state: The context state for the exporter. batch_size: Number of spans to batch before exporting, default is 100. flush_interval: Time in seconds between automatic batch flushes, default is 5.0. max_queue_size: Maximum number of spans to queue, default is 1000. drop_on_overflow: Whether to drop spans when queue is full, default is False. shutdown_timeout: Maximum time to wait for export completion during shutdown, default is 10.0. resource_attributes: Additional resource attributes for spans. redaction_attributes: List of span attribute keys to redact when conditions are met. redaction_headers: List of header keys to check for authentication/user identification. redaction_callback: Function that returns true to redact spans based on header value, false otherwise. redaction_enabled: Whether the redaction processor is enabled, default is False. force_redaction: If True, always redact regardless of header checks, default is False. redaction_value: Value to replace redacted attributes with, default is “[REDACTED]”. tags: Mapping of tag keys to their values (enums or strings) to add to spans. redaction_tag: Tag to add to spans when redaction occurs. endpoint: The endpoint for the OTLP service. headers: The headers for the OTLP service. otlp_kwargs: Additional keyword arguments for the OTLP service.