nvidia-nat 1.1.0a20251020__py3-none-any.whl

nat/observability/exporter/span_exporter.py

@@ -0,0 +1,308 @@
+# 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 os
+import re
+import typing
+from abc import abstractmethod
+from typing import TypeVar
+
+from nat.data_models.intermediate_step import IntermediateStep
+from nat.data_models.intermediate_step import IntermediateStepState
+from nat.data_models.intermediate_step import TraceMetadata
+from nat.data_models.span import MimeTypes
+from nat.data_models.span import Span
+from nat.data_models.span import SpanAttributes
+from nat.data_models.span import SpanContext
+from nat.data_models.span import event_type_to_span_kind
+from nat.observability.exporter.base_exporter import IsolatedAttribute
+from nat.observability.exporter.processing_exporter import ProcessingExporter
+from nat.observability.mixin.serialize_mixin import SerializeMixin
+from nat.observability.utils.dict_utils import merge_dicts
+from nat.observability.utils.time_utils import ns_timestamp
+from nat.utils.type_utils import override
+
+if typing.TYPE_CHECKING:
+    from nat.builder.context import ContextState
+
+logger = logging.getLogger(__name__)
+
+InputSpanT = TypeVar("InputSpanT")
+OutputSpanT = TypeVar("OutputSpanT")
+
+
+class SpanExporter(ProcessingExporter[InputSpanT, OutputSpanT], 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.
+    """
+
+    # Use descriptors for automatic isolation of span-specific state
+    _outstanding_spans: IsolatedAttribute[dict] = IsolatedAttribute(dict)
+    _span_stack: IsolatedAttribute[dict] = IsolatedAttribute(dict)
+    _metadata_stack: IsolatedAttribute[dict] = IsolatedAttribute(dict)
+
+    def __init__(self, context_state: "ContextState | None" = None, span_prefix: str | None = None):
+        super().__init__(context_state=context_state)
+        if span_prefix is None:
+            span_prefix = os.getenv("NAT_SPAN_PREFIX", "nat").strip() or "nat"
+
+        self._span_prefix = span_prefix
+
+    @abstractmethod
+    async def export_processed(self, item: OutputSpanT) -> None:
+        """Export the processed span.
+
+        Args:
+            item (OutputSpanT): The processed span to export.
+        """
+        pass
+
+    @override
+    def export(self, event: IntermediateStep) -> None:
+        """The main logic that reacts to each IntermediateStep.
+
+        Args:
+            event (IntermediateStep): The event to process.
+        """
+        if not isinstance(event, IntermediateStep):
+            return
+
+        if (event.event_state == IntermediateStepState.START):
+            self._process_start_event(event)
+        elif (event.event_state == IntermediateStepState.END):
+            self._process_end_event(event)
+
+    def _process_start_event(self, event: IntermediateStep):
+        """Process the start event of an intermediate step.
+
+        Args:
+            event (IntermediateStep): The event to process.
+        """
+
+        parent_span = None
+        span_ctx = None
+        workflow_trace_id = self._context_state.workflow_trace_id.get()
+
+        # Look up the parent span to establish hierarchy
+        # event.parent_id is the UUID of the last START step with a different UUID from current step
+        # This maintains proper parent-child relationships in the span tree
+        # Skip lookup if parent_id is "root" (indicates this is a top-level span)
+        if len(self._span_stack) > 0 and event.parent_id and event.parent_id != "root":
+
+            parent_span = self._span_stack.get(event.parent_id, None)
+            if parent_span is None:
+                logger.warning("No parent span found for step %s", event.UUID)
+                return
+
+            parent_span = parent_span.model_copy() if isinstance(parent_span, Span) else None
+            if parent_span and parent_span.context:
+                span_ctx = SpanContext(trace_id=parent_span.context.trace_id)
+        # No parent: adopt workflow trace id if available to keep all spans in the same trace
+        if span_ctx is None and workflow_trace_id:
+            span_ctx = SpanContext(trace_id=workflow_trace_id)
+
+        # Extract start/end times from the step
+        # By convention, `span_event_timestamp` is the time we started, `event_timestamp` is the time we ended.
+        # If span_event_timestamp is missing, we default to event_timestamp (meaning zero-length).
+        s_ts = event.payload.span_event_timestamp or event.payload.event_timestamp
+        start_ns = ns_timestamp(s_ts)
+
+        # Optional: embed the LLM/tool name if present
+        if event.payload.name:
+            sub_span_name = f"{event.payload.name}"
+        else:
+            sub_span_name = f"{event.payload.event_type}"
+
+        # Prefer parent/context trace id for attribute, else workflow trace id
+        _attr_trace_id = None
+        if span_ctx is not None:
+            _attr_trace_id = span_ctx.trace_id
+        elif parent_span and parent_span.context:
+            _attr_trace_id = parent_span.context.trace_id
+        elif workflow_trace_id:
+            _attr_trace_id = workflow_trace_id
+
+        attributes = {
+            f"{self._span_prefix}.event_type":
+                event.payload.event_type.value,
+            f"{self._span_prefix}.function.id":
+                event.function_ancestry.function_id if event.function_ancestry else "unknown",
+            f"{self._span_prefix}.function.name":
+                event.function_ancestry.function_name if event.function_ancestry else "unknown",
+            f"{self._span_prefix}.subspan.name":
+                event.payload.name or "",
+            f"{self._span_prefix}.event_timestamp":
+                event.event_timestamp,
+            f"{self._span_prefix}.framework":
+                event.payload.framework.value if event.payload.framework else "unknown",
+            f"{self._span_prefix}.conversation.id":
+                self._context_state.conversation_id.get() or "unknown",
+            f"{self._span_prefix}.workflow.run_id":
+                self._context_state.workflow_run_id.get() or "unknown",
+            f"{self._span_prefix}.workflow.trace_id": (f"{_attr_trace_id:032x}" if _attr_trace_id else "unknown"),
+        }
+
+        sub_span = Span(name=sub_span_name,
+                        parent=parent_span,
+                        context=span_ctx,
+                        attributes=attributes,
+                        start_time=start_ns)
+
+        span_kind = event_type_to_span_kind(event.event_type)
+        sub_span.set_attribute(f"{self._span_prefix}.span.kind", span_kind.value)
+
+        if event.payload.data and event.payload.data.input:
+            match = re.search(r"Human:\s*Question:\s*(.*)", str(event.payload.data.input))
+            if match:
+                human_question = match.group(1).strip()
+                sub_span.set_attribute(SpanAttributes.INPUT_VALUE.value, human_question)
+            else:
+                serialized_input, is_json = self._serialize_payload(event.payload.data.input)
+                sub_span.set_attribute(SpanAttributes.INPUT_VALUE.value, serialized_input)
+                sub_span.set_attribute(SpanAttributes.INPUT_MIME_TYPE.value,
+                                       MimeTypes.JSON.value if is_json else MimeTypes.TEXT.value)
+
+        # Add metadata to the metadata stack
+        start_metadata = event.payload.metadata or {}
+
+        if isinstance(start_metadata, dict):
+            self._metadata_stack[event.UUID] = start_metadata  # type: ignore
+        elif isinstance(start_metadata, TraceMetadata):
+            self._metadata_stack[event.UUID] = start_metadata.model_dump()  # type: ignore
+        else:
+            logger.warning("Invalid metadata type for step %s", event.UUID)
+            return
+
+        self._span_stack[event.UUID] = sub_span  # type: ignore
+        self._outstanding_spans[event.UUID] = sub_span  # type: ignore
+
+        logger.debug(
+            "Added span to tracking (outstanding: %d, stack: %d, event_id: %s)",
+            len(self._outstanding_spans),  # type: ignore
+            len(self._span_stack),  # type: ignore
+            event.UUID)
+
+    def _process_end_event(self, event: IntermediateStep):
+        """Process the end event of an intermediate step.
+
+        Args:
+            event (IntermediateStep): The event to process.
+        """
+
+        # Find the subspan that was created in the start event
+        sub_span: Span | None = self._outstanding_spans.pop(event.UUID, None)  # type: ignore
+
+        if sub_span is None:
+            logger.warning("No subspan found for step %s", event.UUID)
+            return
+
+        self._span_stack.pop(event.UUID, None)  # type: ignore
+
+        # Optionally add more attributes from usage_info or data
+        usage_info = event.payload.usage_info
+        if usage_info:
+            sub_span.set_attribute(SpanAttributes.NAT_USAGE_NUM_LLM_CALLS.value,
+                                   usage_info.num_llm_calls if usage_info.num_llm_calls else 0)
+            sub_span.set_attribute(SpanAttributes.NAT_USAGE_SECONDS_BETWEEN_CALLS.value,
+                                   usage_info.seconds_between_calls if usage_info.seconds_between_calls else 0)
+            sub_span.set_attribute(SpanAttributes.LLM_TOKEN_COUNT_PROMPT.value,
+                                   usage_info.token_usage.prompt_tokens if usage_info.token_usage else 0)
+            sub_span.set_attribute(SpanAttributes.LLM_TOKEN_COUNT_COMPLETION.value,
+                                   usage_info.token_usage.completion_tokens if usage_info.token_usage else 0)
+            sub_span.set_attribute(SpanAttributes.LLM_TOKEN_COUNT_TOTAL.value,
+                                   usage_info.token_usage.total_tokens if usage_info.token_usage else 0)
+
+        if event.payload.data and event.payload.data.output is not None:
+            serialized_output, is_json = self._serialize_payload(event.payload.data.output)
+            sub_span.set_attribute(SpanAttributes.OUTPUT_VALUE.value, serialized_output)
+            sub_span.set_attribute(SpanAttributes.OUTPUT_MIME_TYPE.value,
+                                   MimeTypes.JSON.value if is_json else MimeTypes.TEXT.value)
+
+        # Merge metadata from start event with end event metadata
+        start_metadata = self._metadata_stack.pop(event.UUID)  # type: ignore
+
+        if start_metadata is None:
+            logger.warning("No metadata found for step %s", event.UUID)
+            return
+
+        end_metadata = event.payload.metadata or {}
+
+        if not isinstance(end_metadata, dict | TraceMetadata):
+            logger.warning("Invalid metadata type for step %s", event.UUID)
+            return
+
+        if isinstance(end_metadata, TraceMetadata):
+            end_metadata = end_metadata.model_dump()
+
+        merged_metadata = merge_dicts(start_metadata, end_metadata)
+        serialized_metadata, is_json = self._serialize_payload(merged_metadata)
+        sub_span.set_attribute(f"{self._span_prefix}.metadata", serialized_metadata)
+        sub_span.set_attribute(f"{self._span_prefix}.metadata.mime_type",
+                               MimeTypes.JSON.value if is_json else MimeTypes.TEXT.value)
+
+        end_ns = ns_timestamp(event.payload.event_timestamp)
+
+        # End the subspan
+        sub_span.end(end_time=end_ns)
+
+        # Export the span with processing pipeline
+        self._create_export_task(self._export_with_processing(sub_span))  # type: ignore
+
+    @override
+    async def _cleanup(self):
+        """Clean up any remaining spans."""
+        if self._outstanding_spans:  # type: ignore
+            logger.warning("Not all spans were closed. Remaining: %s", self._outstanding_spans)  # type: ignore
+
+            for span_info in self._outstanding_spans.values():  # type: ignore
+                span_info.end()
+
+        self._outstanding_spans.clear()  # type: ignore
+        self._span_stack.clear()  # type: ignore
+        self._metadata_stack.clear()  # type: ignore
+        await super()._cleanup()

nat/observability/exporter_manager.py

@@ -0,0 +1,335 @@
+# 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 asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from nat.builder.context import ContextState
+from nat.observability.exporter.base_exporter import BaseExporter
+
+logger = logging.getLogger(__name__)
+
+
+class ExporterManager:
+    """
+    Manages the lifecycle of asynchronous exporters.
+
+    ExporterManager maintains a registry of exporters, allowing for dynamic addition and removal. It provides
+    methods to start and stop all registered exporters concurrently, ensuring proper synchronization and
+    lifecycle management. The manager is designed to prevent race conditions during exporter operations and to
+    handle exporter tasks in an asyncio event loop.
+
+    Each workflow execution gets its own ExporterManager instance to manage the lifecycle of exporters
+    during that workflow's execution.
+
+    Exporters added after `start()` is called will not be started automatically. They will only be
+    started on the next lifecycle (i.e., after a stop and subsequent start).
+
+    Args:
+        shutdown_timeout (int, optional): Maximum time in seconds to wait for exporters to shut down gracefully.
+        Defaults to 120 seconds.
+    """
+
+    def __init__(self, shutdown_timeout: int = 120):
+        """Initialize the ExporterManager."""
+        self._tasks: dict[str, asyncio.Task] = {}
+        self._running: bool = False
+        self._exporter_registry: dict[str, BaseExporter] = {}
+        self._is_registry_shared: bool = False
+        self._lock: asyncio.Lock = asyncio.Lock()
+        self._shutdown_event: asyncio.Event = asyncio.Event()
+        self._shutdown_timeout: int = shutdown_timeout
+        # Track isolated exporters for proper cleanup
+        self._active_isolated_exporters: dict[str, BaseExporter] = {}
+
+    @classmethod
+    def _create_with_shared_registry(cls, shutdown_timeout: int,
+                                     shared_registry: dict[str, BaseExporter]) -> "ExporterManager":
+        """Internal factory method for creating instances with shared registry."""
+        instance = cls.__new__(cls)
+        instance._tasks = {}
+        instance._running = False
+        instance._exporter_registry = shared_registry
+        instance._is_registry_shared = True
+        instance._lock = asyncio.Lock()
+        instance._shutdown_event = asyncio.Event()
+        instance._shutdown_timeout = shutdown_timeout
+        instance._active_isolated_exporters = {}
+        return instance
+
+    def _ensure_registry_owned(self):
+        """Ensure we own the registry (copy-on-write)."""
+        if self._is_registry_shared:
+            self._exporter_registry = self._exporter_registry.copy()
+            self._is_registry_shared = False
+
+    def add_exporter(self, name: str, exporter: BaseExporter) -> None:
+        """
+        Add an exporter to the manager.
+
+        Args:
+            name (str): The unique name for the exporter.
+            exporter (BaseExporter): The exporter instance to add.
+        """
+        self._ensure_registry_owned()
+
+        if name in self._exporter_registry:
+            logger.warning("Exporter '%s' already registered. Overwriting.", name)
+
+        self._exporter_registry[name] = exporter
+
+    def remove_exporter(self, name: str) -> None:
+        """
+        Remove an exporter from the manager.
+
+        Args:
+            name (str): The name of the exporter to remove.
+        """
+        self._ensure_registry_owned()
+        if name in self._exporter_registry:
+            del self._exporter_registry[name]
+        else:
+            raise ValueError(f"Cannot remove exporter '{name}' because it is not registered.")
+
+    def get_exporter(self, name: str) -> BaseExporter:
+        """
+        Get an exporter instance by name.
+
+        Args:
+            name (str): The name of the exporter to retrieve.
+
+        Returns:
+            BaseExporter: The exporter instance if found, otherwise raises a ValueError.
+
+        Raises:
+            ValueError: If the exporter is not found.
+        """
+        exporter = self._exporter_registry.get(name, None)
+
+        if exporter is not None:
+            return exporter
+
+        raise ValueError(f"Cannot get exporter '{name}' because it is not registered.")
+
+    async def get_all_exporters(self) -> dict[str, BaseExporter]:
+        """
+        Get all registered exporters instances.
+
+        Returns:
+            dict[str, BaseExporter]: A dictionary mapping exporter names to exporter instances.
+        """
+        return self._exporter_registry
+
+    def create_isolated_exporters(self, context_state: ContextState | None = None) -> dict[str, BaseExporter]:
+        """
+        Create isolated copies of all exporters for concurrent execution.
+
+        This uses copy-on-write to efficiently create isolated instances that share
+        expensive resources but have separate mutable state.
+
+        Args:
+            context_state (ContextState | None, optional): The isolated context state for the new exporter instances.
+                If not provided, a new context state will be created.
+
+        Returns:
+            dict[str, BaseExporter]: Dictionary of isolated exporter instances
+        """
+        # Provide default context state if None
+        if context_state is None:
+            context_state = ContextState.get()
+
+        isolated_exporters = {}
+        for name, exporter in self._exporter_registry.items():
+            if hasattr(exporter, 'create_isolated_instance'):
+                isolated_exporters[name] = exporter.create_isolated_instance(context_state)
+            else:
+                # Fallback for exporters that don't support isolation
+                logger.warning("Exporter '%s' doesn't support isolation, using shared instance", name)
+                isolated_exporters[name] = exporter
+        return isolated_exporters
+
+    async def _cleanup_isolated_exporters(self):
+        """Explicitly clean up isolated exporter instances."""
+        if not self._active_isolated_exporters:
+            return
+
+        logger.debug("Cleaning up %d isolated exporters", len(self._active_isolated_exporters))
+
+        cleanup_tasks = []
+        for name, exporter in self._active_isolated_exporters.items():
+            try:
+                # Only clean up isolated instances that have a stop method
+                if hasattr(exporter, 'stop') and exporter.is_isolated_instance:
+                    cleanup_tasks.append(self._cleanup_single_exporter(name, exporter))
+                else:
+                    logger.debug("Skipping cleanup for non-isolated exporter '%s'", name)
+            except Exception as e:
+                logger.exception("Error preparing cleanup for isolated exporter '%s': %s", name, e)
+
+        if cleanup_tasks:
+            # Run cleanup tasks concurrently with timeout
+            try:
+                await asyncio.wait_for(asyncio.gather(*cleanup_tasks, return_exceptions=True),
+                                       timeout=self._shutdown_timeout)
+            except TimeoutError:
+                logger.warning("Some isolated exporters did not clean up within timeout")
+
+        self._active_isolated_exporters.clear()
+
+    async def _cleanup_single_exporter(self, name: str, exporter: BaseExporter):
+        """Clean up a single isolated exporter."""
+        try:
+            logger.debug("Stopping isolated exporter '%s'", name)
+            await exporter.stop()
+        except Exception as e:
+            logger.exception("Error stopping isolated exporter '%s': %s", name, e)
+
+    @asynccontextmanager
+    async def start(self, context_state: ContextState | None = None):
+        """
+        Start all registered exporters concurrently.
+
+        This method acquires a lock to ensure only one start/stop cycle is active at a time. It starts all
+        currently registered exporters in their own asyncio tasks. Exporters added after this call will not be
+        started until the next lifecycle.
+
+        Args:
+            context_state: Optional context state for creating isolated exporters
+
+        Yields:
+            ExporterManager: The manager instance for use within the context.
+
+        Raises:
+            RuntimeError: If the manager is already running.
+        """
+        async with self._lock:
+            if self._running:
+                raise RuntimeError("Exporter manager is already running")
+            self._shutdown_event.clear()
+            self._running = True
+
+            # Create isolated exporters if context_state provided, otherwise use originals
+            if context_state:
+                exporters_to_start = self.create_isolated_exporters(context_state)
+                # Store isolated exporters for cleanup
+                self._active_isolated_exporters = exporters_to_start
+                logger.debug("Created %d isolated exporters", len(exporters_to_start))
+            else:
+                exporters_to_start = self._exporter_registry
+                # Clear isolated exporters since we're using originals
+                self._active_isolated_exporters = {}
+
+            # Start all exporters concurrently
+            exporters = []
+            tasks = []
+            for name, exporter in exporters_to_start.items():
+                task = asyncio.create_task(self._run_exporter(name, exporter))
+                exporters.append(exporter)
+                self._tasks[name] = task
+                tasks.append(task)
+
+            # Wait for all exporters to be ready
+            await asyncio.gather(*[exporter.wait_ready() for exporter in exporters])
+
+        try:
+            yield self
+        finally:
+            # Clean up isolated exporters BEFORE stopping tasks
+            try:
+                await self._cleanup_isolated_exporters()
+            except Exception as e:
+                logger.exception("Error during isolated exporter cleanup: %s", e)
+
+            # Then stop the manager tasks
+            await self.stop()
+
+    async def _run_exporter(self, name: str, exporter: BaseExporter):
+        """
+        Run an exporter in its own task.
+
+        Args:
+            name (str): The name of the exporter.
+            exporter (BaseExporter): The exporter instance to run.
+        """
+        try:
+            async with exporter.start():
+                logger.info("Started exporter '%s'", name)
+                # The context manager will keep the task alive until shutdown is signaled
+                await self._shutdown_event.wait()
+                logger.info("Stopped exporter '%s'", name)
+        except asyncio.CancelledError:
+            logger.debug("Exporter '%s' task cancelled", name)
+            logger.info("Stopped exporter '%s'", name)
+            raise
+        except Exception as e:
+            logger.error("Failed to run exporter '%s': %s", name, str(e))
+            # Re-raise the exception to ensure it's properly handled
+            raise
+
+    async def stop(self) -> None:
+        """
+        Stop all registered exporters.
+
+        This method signals all running exporter tasks to shut down and waits for their completion, up to the
+        configured shutdown timeout. If any tasks do not complete in time, a warning is logged.
+        """
+        async with self._lock:
+            if not self._running:
+                return
+            self._running = False
+            self._shutdown_event.set()
+
+        # Create a copy of tasks to prevent modification during iteration
+        tasks_to_cancel = dict(self._tasks)
+        self._tasks.clear()
+        stuck_tasks = []
+        # Cancel all running tasks and await their completion
+        for name, task in tasks_to_cancel.items():
+            try:
+                task.cancel()
+                await asyncio.wait_for(task, timeout=self._shutdown_timeout)
+            except TimeoutError:
+                logger.warning("Exporter '%s' task did not shut down in time and may be stuck.", name)
+                stuck_tasks.append(name)
+            except asyncio.CancelledError:
+                logger.debug("Exporter '%s' task cancelled", name)
+            except Exception as e:
+                logger.exception("Failed to stop exporter '%s': %s", name, str(e))
+
+        if stuck_tasks:
+            logger.warning("Exporters did not shut down in time: %s", ", ".join(stuck_tasks))
+
+    @staticmethod
+    def from_exporters(exporters: dict[str, BaseExporter], shutdown_timeout: int = 120) -> "ExporterManager":
+        """
+        Create an ExporterManager from a dictionary of exporters.
+        """
+        exporter_manager = ExporterManager(shutdown_timeout=shutdown_timeout)
+        for name, exporter in exporters.items():
+            exporter_manager.add_exporter(name, exporter)
+
+        return exporter_manager
+
+    def get(self) -> "ExporterManager":
+        """
+        Create a copy of this ExporterManager with the same configuration using copy-on-write.
+
+        This is the most efficient approach - shares the registry until modifications are needed.
+
+        Returns:
+            ExporterManager: A new ExporterManager instance with shared exporters (copy-on-write).
+        """
+        return self._create_with_shared_registry(self._shutdown_timeout, self._exporter_registry)

nat/observability/mixin/__init__.py

@@ -0,0 +1,14 @@
+# 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.

nat/observability/mixin/batch_config_mixin.py

@@ -0,0 +1,26 @@
+# 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.
+
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class BatchConfigMixin(BaseModel):
+    """Mixin for telemetry exporters that require batching."""
+    batch_size: int = Field(default=100, description="The batch size for the telemetry exporter.")
+    flush_interval: float = Field(default=5.0, description="The flush interval for the telemetry exporter.")
+    max_queue_size: int = Field(default=1000, description="The maximum queue size for the telemetry exporter.")
+    drop_on_overflow: bool = Field(default=False, description="Whether to drop on overflow for the telemetry exporter.")
+    shutdown_timeout: float = Field(default=10.0, description="The shutdown timeout for the telemetry exporter.")