nvidia-nat-opentelemetry 1.2.0__py3-none-any.whl

nat/plugins/opentelemetry/otel_span_exporter.py

@@ -0,0 +1,166 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from abc import abstractmethod
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+
+from opentelemetry.sdk.resources import Resource
+
+from nat.builder.context import ContextState
+from nat.data_models.span import Span
+from nat.observability.exporter.span_exporter import SpanExporter
+from nat.observability.processor.batching_processor import BatchingProcessor
+from nat.observability.processor.processor import Processor
+from nat.plugins.opentelemetry.otel_span import OtelSpan
+from nat.plugins.opentelemetry.span_converter import convert_span_to_otel
+
+logger = logging.getLogger(__name__)
+
+
+def get_opentelemetry_sdk_version() -> str:
+    """Get the OpenTelemetry SDK version dynamically.
+
+    Returns:
+        The version of the opentelemetry-sdk package, or 'unknown' if not found.
+    """
+    try:
+        return version("opentelemetry-sdk")
+    except PackageNotFoundError:
+        logger.warning("Could not determine opentelemetry-sdk version")
+        return "unknown"
+
+
+class SpanToOtelProcessor(Processor[Span, OtelSpan]):
+    """Processor that converts a Span to an OtelSpan."""
+
+    async def process(self, item: Span) -> OtelSpan:
+        return convert_span_to_otel(item)  # type: ignore
+
+
+class OtelSpanBatchProcessor(BatchingProcessor[OtelSpan]):
+    """Processor that batches OtelSpans with explicit type information.
+
+    This class provides explicit type information for the TypeIntrospectionMixin
+    by overriding the type properties directly.
+    """
+    pass
+
+
+class OtelSpanExporter(SpanExporter[Span, OtelSpan]):  # pylint: disable=R0901
+    """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)
+    """
+
+    def __init__(self,
+                 context_state: 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):
+        """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.
+        """
+        super().__init__(context_state)
+
+        # Initialize resource for span attribution
+        if resource_attributes is None:
+            resource_attributes = {}
+        self._resource = Resource(attributes=resource_attributes)
+
+        self.add_processor(SpanToOtelProcessor())
+        self.add_processor(
+            OtelSpanBatchProcessor(batch_size=batch_size,
+                                   flush_interval=flush_interval,
+                                   max_queue_size=max_queue_size,
+                                   drop_on_overflow=drop_on_overflow,
+                                   shutdown_timeout=shutdown_timeout))
+
+    async def export_processed(self, item: OtelSpan | list[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.
+        """
+        try:
+            if isinstance(item, OtelSpan):
+                spans = [item]
+            elif isinstance(item, list):
+                spans = item
+            else:
+                logger.warning("Unexpected item type: %s", type(item))
+                return
+
+            # Set resource attributes on all spans
+            for span in spans:
+                span.set_resource(self._resource)
+
+            # Delegate to concrete implementation
+            await self.export_otel_spans(spans)
+
+        except Exception as e:
+            logger.error("Error exporting spans: %s", e, exc_info=True)
+
+    @abstractmethod
+    async def export_otel_spans(self, spans: list[OtelSpan]) -> None:
+        """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.
+        """
+        pass

nat/plugins/opentelemetry/otlp_span_adapter_exporter.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+from nat.builder.context import ContextState
+from nat.plugins.opentelemetry.mixin.otlp_span_exporter_mixin import OTLPSpanExporterMixin
+from nat.plugins.opentelemetry.otel_span_exporter import OtelSpanExporter
+
+logger = logging.getLogger(__name__)
+
+
+class OTLPSpanAdapterExporter(OTLPSpanExporterMixin, OtelSpanExporter):  # pylint: disable=R0901
+    """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
+        )
+    """
+
+    def __init__(
+            self,
+            *,
+            # OtelSpanExporter args
+            context_state: 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,
+            # OTLPSpanExporterMixin args
+            endpoint: str,
+            headers: dict[str, str] | None = None,
+            **otlp_kwargs):
+        """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.
+        """
+        super().__init__(context_state=context_state,
+                         batch_size=batch_size,
+                         flush_interval=flush_interval,
+                         max_queue_size=max_queue_size,
+                         drop_on_overflow=drop_on_overflow,
+                         shutdown_timeout=shutdown_timeout,
+                         resource_attributes=resource_attributes,
+                         endpoint=endpoint,
+                         headers=headers,
+                         **otlp_kwargs)

nat/plugins/opentelemetry/register.py

@@ -0,0 +1,195 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import os
+
+from pydantic import Field
+
+from nat.builder.builder import Builder
+from nat.cli.register_workflow import register_telemetry_exporter
+from nat.data_models.telemetry_exporter import TelemetryExporterBaseConfig
+from nat.observability.mixin.batch_config_mixin import BatchConfigMixin
+from nat.observability.mixin.collector_config_mixin import CollectorConfigMixin
+
+logger = logging.getLogger(__name__)
+
+
+class LangfuseTelemetryExporter(BatchConfigMixin, TelemetryExporterBaseConfig, name="langfuse"):
+    """A telemetry exporter to transmit traces to externally hosted langfuse service."""
+
+    endpoint: str = Field(description="The langfuse OTEL endpoint (/api/public/otel/v1/traces)")
+    public_key: str = Field(description="The Langfuse public key", default="")
+    secret_key: str = Field(description="The Langfuse secret key", default="")
+    resource_attributes: dict[str, str] = Field(default_factory=dict,
+                                                description="The resource attributes to add to the span")
+
+
+@register_telemetry_exporter(config_type=LangfuseTelemetryExporter)
+async def langfuse_telemetry_exporter(config: LangfuseTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+
+    import base64
+
+    from nat.plugins.opentelemetry.otlp_span_adapter_exporter import OTLPSpanAdapterExporter
+
+    secret_key = config.secret_key or os.environ.get("LANGFUSE_SECRET_KEY")
+    public_key = config.public_key or os.environ.get("LANGFUSE_PUBLIC_KEY")
+    if not secret_key or not public_key:
+        raise ValueError("secret and public keys are required for langfuse")
+
+    credentials = f"{public_key}:{secret_key}".encode("utf-8")
+    auth_header = base64.b64encode(credentials).decode("utf-8")
+    headers = {"Authorization": f"Basic {auth_header}"}
+
+    yield OTLPSpanAdapterExporter(endpoint=config.endpoint,
+                                  headers=headers,
+                                  batch_size=config.batch_size,
+                                  flush_interval=config.flush_interval,
+                                  max_queue_size=config.max_queue_size,
+                                  drop_on_overflow=config.drop_on_overflow,
+                                  shutdown_timeout=config.shutdown_timeout)
+
+
+class LangsmithTelemetryExporter(BatchConfigMixin, CollectorConfigMixin, TelemetryExporterBaseConfig, name="langsmith"):
+    """A telemetry exporter to transmit traces to externally hosted langsmith service."""
+
+    endpoint: str = Field(
+        description="The langsmith OTEL endpoint",
+        default="https://api.smith.langchain.com/otel/v1/traces",
+    )
+    api_key: str = Field(description="The Langsmith API key", default="")
+    resource_attributes: dict[str, str] = Field(default_factory=dict,
+                                                description="The resource attributes to add to the span")
+
+
+@register_telemetry_exporter(config_type=LangsmithTelemetryExporter)
+async def langsmith_telemetry_exporter(config: LangsmithTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+    """Create a Langsmith telemetry exporter."""
+
+    from nat.plugins.opentelemetry.otlp_span_adapter_exporter import OTLPSpanAdapterExporter
+
+    api_key = config.api_key or os.environ.get("LANGSMITH_API_KEY")
+    if not api_key:
+        raise ValueError("API key is required for langsmith")
+
+    headers = {"x-api-key": api_key, "Langsmith-Project": config.project}
+    yield OTLPSpanAdapterExporter(endpoint=config.endpoint,
+                                  headers=headers,
+                                  batch_size=config.batch_size,
+                                  flush_interval=config.flush_interval,
+                                  max_queue_size=config.max_queue_size,
+                                  drop_on_overflow=config.drop_on_overflow,
+                                  shutdown_timeout=config.shutdown_timeout)
+
+
+class OtelCollectorTelemetryExporter(BatchConfigMixin,
+                                     CollectorConfigMixin,
+                                     TelemetryExporterBaseConfig,
+                                     name="otelcollector"):
+    """A telemetry exporter to transmit traces to externally hosted otel collector service."""
+
+    resource_attributes: dict[str, str] = Field(default_factory=dict,
+                                                description="The resource attributes to add to the span")
+
+
+@register_telemetry_exporter(config_type=OtelCollectorTelemetryExporter)
+async def otel_telemetry_exporter(config: OtelCollectorTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+    """Create an OpenTelemetry telemetry exporter."""
+
+    from nat.plugins.opentelemetry.otel_span_exporter import get_opentelemetry_sdk_version
+    from nat.plugins.opentelemetry.otlp_span_adapter_exporter import OTLPSpanAdapterExporter
+
+    # Default resource attributes
+    default_resource_attributes = {
+        "telemetry.sdk.language": "python",
+        "telemetry.sdk.name": "opentelemetry",
+        "telemetry.sdk.version": get_opentelemetry_sdk_version(),
+        "service.name": config.project,
+    }
+
+    # Merge defaults with config, giving precedence to config
+    merged_resource_attributes = {**default_resource_attributes, **config.resource_attributes}
+
+    yield OTLPSpanAdapterExporter(endpoint=config.endpoint,
+                                  resource_attributes=merged_resource_attributes,
+                                  batch_size=config.batch_size,
+                                  flush_interval=config.flush_interval,
+                                  max_queue_size=config.max_queue_size,
+                                  drop_on_overflow=config.drop_on_overflow,
+                                  shutdown_timeout=config.shutdown_timeout)
+
+
+class PatronusTelemetryExporter(BatchConfigMixin, CollectorConfigMixin, TelemetryExporterBaseConfig, name="patronus"):
+    """A telemetry exporter to transmit traces to Patronus service."""
+
+    api_key: str = Field(description="The Patronus API key", default="")
+    resource_attributes: dict[str, str] = Field(default_factory=dict,
+                                                description="The resource attributes to add to the span")
+
+
+@register_telemetry_exporter(config_type=PatronusTelemetryExporter)
+async def patronus_telemetry_exporter(config: PatronusTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+    """Create a Patronus telemetry exporter."""
+
+    from nat.plugins.opentelemetry.otlp_span_adapter_exporter import OTLPSpanAdapterExporter
+
+    api_key = config.api_key or os.environ.get("PATRONUS_API_KEY")
+    if not api_key:
+        raise ValueError("API key is required for Patronus")
+
+    headers = {
+        "x-api-key": api_key,
+        "pat-project-name": config.project,
+    }
+    yield OTLPSpanAdapterExporter(endpoint=config.endpoint,
+                                  headers=headers,
+                                  batch_size=config.batch_size,
+                                  flush_interval=config.flush_interval,
+                                  max_queue_size=config.max_queue_size,
+                                  drop_on_overflow=config.drop_on_overflow,
+                                  shutdown_timeout=config.shutdown_timeout)
+
+
+# pylint: disable=W0613
+class GalileoTelemetryExporter(BatchConfigMixin, CollectorConfigMixin, TelemetryExporterBaseConfig, name="galileo"):
+    """A telemetry exporter to transmit traces to externally hosted galileo service."""
+
+    endpoint: str = Field(description="The galileo endpoint to export telemetry traces.",
+                          default="https://app.galileo.ai/api/galileo/otel/traces")
+    logstream: str = Field(description="The logstream name to group the telemetry traces.")
+    api_key: str = Field(description="The api key to authenticate with the galileo service.")
+
+
+@register_telemetry_exporter(config_type=GalileoTelemetryExporter)
+async def galileo_telemetry_exporter(config: GalileoTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+    """Create a Galileo telemetry exporter."""
+
+    from nat.plugins.opentelemetry.otlp_span_adapter_exporter import OTLPSpanAdapterExporter
+
+    headers = {
+        "Galileo-API-Key": config.api_key,
+        "logstream": config.logstream,
+        "project": config.project,
+    }
+
+    yield OTLPSpanAdapterExporter(
+        endpoint=config.endpoint,
+        headers=headers,
+        batch_size=config.batch_size,
+        flush_interval=config.flush_interval,
+        max_queue_size=config.max_queue_size,
+        drop_on_overflow=config.drop_on_overflow,
+        shutdown_timeout=config.shutdown_timeout,
+    )

nat/plugins/opentelemetry/span_converter.py

@@ -0,0 +1,228 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import time
+
+from openinference.semconv.trace import OpenInferenceSpanKindValues
+from openinference.semconv.trace import SpanAttributes
+from opentelemetry.trace import SpanContext
+from opentelemetry.trace import SpanKind
+from opentelemetry.trace import Status
+from opentelemetry.trace import StatusCode
+from opentelemetry.trace import TraceFlags
+
+from nat.data_models.span import Span
+from nat.data_models.span import SpanStatusCode
+from nat.plugins.opentelemetry.otel_span import OtelSpan
+
+logger = logging.getLogger(__name__)
+
+SPAN_EVENT_TYPE_TO_SPAN_KIND_MAP = {
+    "LLM_START": OpenInferenceSpanKindValues.LLM,
+    "LLM_END": OpenInferenceSpanKindValues.LLM,
+    "LLM_NEW_TOKEN": OpenInferenceSpanKindValues.LLM,
+    "TOOL_START": OpenInferenceSpanKindValues.TOOL,
+    "TOOL_END": OpenInferenceSpanKindValues.TOOL,
+    "FUNCTION_START": OpenInferenceSpanKindValues.CHAIN,
+    "FUNCTION_END": OpenInferenceSpanKindValues.CHAIN,
+    "WORKFLOW_START": OpenInferenceSpanKindValues.CHAIN,
+    "WORKFLOW_END": OpenInferenceSpanKindValues.CHAIN,
+    "TASK_START": OpenInferenceSpanKindValues.CHAIN,
+    "TASK_END": OpenInferenceSpanKindValues.CHAIN,
+    "CUSTOM_START": OpenInferenceSpanKindValues.CHAIN,
+    "CUSTOM_END": OpenInferenceSpanKindValues.CHAIN,
+    "EMBEDDER_START": OpenInferenceSpanKindValues.EMBEDDING,
+    "EMBEDDER_END": OpenInferenceSpanKindValues.EMBEDDING,
+    "RETRIEVER_START": OpenInferenceSpanKindValues.RETRIEVER,
+    "RETRIEVER_END": OpenInferenceSpanKindValues.RETRIEVER,
+    "AGENT_START": OpenInferenceSpanKindValues.AGENT,
+    "AGENT_END": OpenInferenceSpanKindValues.AGENT,
+    "RERANKER_START": OpenInferenceSpanKindValues.RERANKER,
+    "RERANKER_END": OpenInferenceSpanKindValues.RERANKER,
+    "GUARDRAIL_START": OpenInferenceSpanKindValues.GUARDRAIL,
+    "GUARDRAIL_END": OpenInferenceSpanKindValues.GUARDRAIL,
+    "EVALUATOR_START": OpenInferenceSpanKindValues.EVALUATOR,
+    "EVALUATOR_END": OpenInferenceSpanKindValues.EVALUATOR,
+}
+
+
+# Reuse expensive objects to avoid repeated creation
+class _SharedObjects:
+
+    def __init__(self):
+        self.resource = None  # type: ignore
+        self.instrumentation_scope = None  # type: ignore
+
+
+_shared = _SharedObjects()
+_SAMPLED_TRACE_FLAGS = TraceFlags(1)
+
+
+def _get_shared_resource():
+    """Get shared resource object to avoid repeated creation."""
+    if _shared.resource is None:
+        from opentelemetry.sdk.resources import Resource
+        _shared.resource = Resource.create()  # type: ignore
+    return _shared.resource
+
+
+def _get_shared_instrumentation_scope():
+    """Get shared instrumentation scope to avoid repeated creation."""
+    if _shared.instrumentation_scope is None:
+        from opentelemetry.sdk.trace import InstrumentationScope
+        _shared.instrumentation_scope = InstrumentationScope("nat", "1.0.0")  # type: ignore
+    return _shared.instrumentation_scope
+
+
+def convert_event_type_to_span_kind(event_type: str) -> OpenInferenceSpanKindValues:
+    """Convert an event type to a span kind.
+
+    Args:
+        event_type (str): The event type to convert
+
+    Returns:
+        OpenInferenceSpanKindValues: The corresponding span kind
+    """
+    return SPAN_EVENT_TYPE_TO_SPAN_KIND_MAP.get(event_type, OpenInferenceSpanKindValues.UNKNOWN)
+
+
+def convert_span_status_code(nat_status_code: SpanStatusCode) -> StatusCode:
+    """Convert NAT SpanStatusCode to OpenTelemetry StatusCode.
+
+    Args:
+        nat_status_code (SpanStatusCode): The NAT span status code to convert
+
+    Returns:
+        StatusCode: The corresponding OpenTelemetry StatusCode
+    """
+    status_map = {
+        SpanStatusCode.OK: StatusCode.OK,
+        SpanStatusCode.ERROR: StatusCode.ERROR,
+        SpanStatusCode.UNSET: StatusCode.UNSET,
+    }
+    return status_map.get(nat_status_code, StatusCode.UNSET)
+
+
+def convert_span_to_otel(nat_span: Span) -> OtelSpan:
+    """Convert a NAT Span to an OtelSpan using ultra-fast conversion.
+
+    Args:
+        nat_span (Span): The NAT span to convert
+
+    Returns:
+        OtelSpan: The converted OtelSpan with proper parent hierarchy.
+    """
+    # Fast path for spans without context
+    if not nat_span.context:
+        # Create minimal OtelSpan bypassing expensive constructor
+        otel_span = object.__new__(OtelSpan)  # Bypass __init__
+        otel_span._name = nat_span.name
+        otel_span._context = None  # type: ignore
+        otel_span._parent = None
+        otel_span._attributes = nat_span.attributes.copy()
+        otel_span._events = []
+        otel_span._links = []
+        otel_span._kind = SpanKind.INTERNAL
+        otel_span._start_time = nat_span.start_time
+        otel_span._end_time = nat_span.end_time
+        otel_span._status = Status(StatusCode.UNSET)
+        otel_span._ended = False
+        otel_span._resource = _get_shared_resource()  # type: ignore
+        otel_span._instrumentation_scope = _get_shared_instrumentation_scope()  # type: ignore
+        otel_span._dropped_attributes = 0
+        otel_span._dropped_events = 0
+        otel_span._dropped_links = 0
+        otel_span._status_description = None
+        return otel_span
+
+    # Process parent efficiently (if needed)
+    parent_otel_span = None
+    trace_id = nat_span.context.trace_id
+
+    if nat_span.parent:
+        parent_otel_span = convert_span_to_otel(nat_span.parent)
+        parent_context = parent_otel_span.get_span_context()
+        trace_id = parent_context.trace_id
+
+    # Create SpanContext efficiently
+    otel_span_context = SpanContext(
+        trace_id=trace_id,
+        span_id=nat_span.context.span_id,
+        is_remote=False,
+        trace_flags=_SAMPLED_TRACE_FLAGS,  # Reuse flags object
+    )
+
+    # Create OtelSpan bypassing expensive constructor
+    otel_span = object.__new__(OtelSpan)  # Bypass __init__
+    otel_span._name = nat_span.name
+    otel_span._context = otel_span_context
+    otel_span._parent = parent_otel_span
+    otel_span._attributes = nat_span.attributes.copy()
+    otel_span._events = []
+    otel_span._links = []
+    otel_span._kind = SpanKind.INTERNAL
+    otel_span._start_time = nat_span.start_time
+    otel_span._end_time = nat_span.end_time
+
+    # Reuse status conversion
+    status_code = convert_span_status_code(nat_span.status.code)
+    otel_span._status = Status(status_code, nat_span.status.message)
+
+    otel_span._ended = False
+    otel_span._resource = _get_shared_resource()  # type: ignore
+    otel_span._instrumentation_scope = _get_shared_instrumentation_scope()  # type: ignore
+    otel_span._dropped_attributes = 0
+    otel_span._dropped_events = 0
+    otel_span._dropped_links = 0
+    otel_span._status_description = None
+
+    # Set span kind efficiently (direct attribute modification)
+    event_type = nat_span.attributes.get("nat.event_type", "UNKNOWN")
+    span_kind = SPAN_EVENT_TYPE_TO_SPAN_KIND_MAP.get(event_type, OpenInferenceSpanKindValues.UNKNOWN)
+    otel_span._attributes[SpanAttributes.OPENINFERENCE_SPAN_KIND] = span_kind.value
+
+    # Process events (only if they exist)
+    if nat_span.events:
+        for nat_event in nat_span.events:
+            # Optimize timestamp handling
+            if isinstance(nat_event.timestamp, int):
+                event_timestamp_ns = nat_event.timestamp
+            elif nat_event.timestamp:
+                event_timestamp_ns = int(nat_event.timestamp)
+            else:
+                event_timestamp_ns = int(time.time() * 1e9)
+
+            # Add event directly to internal list (bypass add_event method)
+            otel_span._events.append({
+                "name": nat_event.name, "attributes": nat_event.attributes, "timestamp": event_timestamp_ns
+            })
+
+    return otel_span
+
+
+def convert_spans_to_otel_batch(spans: list[Span]) -> list[OtelSpan]:
+    """Convert a list of NAT spans to OtelSpans using stateless conversion.
+
+    This is useful for batch processing or demos. Each span is converted
+    independently using the stateless approach.
+
+    Args:
+        spans (list[Span]): List of NAT spans to convert
+
+    Returns:
+        list[OtelSpan]: List of converted OtelSpans with proper parent-child relationships
+    """
+    return [convert_span_to_otel(span) for span in spans]