nvidia-nat 1.2.0__py3-none-any.whl

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.error("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 asyncio.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.error("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.error("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), exc_info=True)
+            # 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 asyncio.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.error("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.")

nat/observability/mixin/collector_config_mixin.py

@@ -0,0 +1,23 @@
+# 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 CollectorConfigMixin(BaseModel):
+    """Mixin for telemetry exporters that require a project name and endpoint when exporting to a collector service."""
+    project: str = Field(description="The project name to associate the telemetry traces.")
+    endpoint: str = Field(description="The endpoint of the telemetry collector service.")

nat/observability/mixin/file_mixin.py

@@ -0,0 +1,288 @@
+# 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 datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from nat.observability.mixin.file_mode import FileMode
+from nat.observability.mixin.resource_conflict_mixin import ResourceConflictMixin
+
+logger = logging.getLogger(__name__)
+
+
+class FileExportMixin(ResourceConflictMixin):
+    """Mixin for file-based exporters.
+
+    This mixin provides file I/O functionality for exporters that need to write
+    serialized data to local files, with support for file overwriting and rolling logs.
+
+    Automatically detects and prevents file path conflicts between multiple instances
+    by raising ResourceConflictError during initialization.
+    """
+
+    def __init__(
+            self,
+            *args,
+            output_path,
+            project,
+            mode: FileMode = FileMode.APPEND,
+            enable_rolling: bool = False,
+            max_file_size: int = 10 * 1024 * 1024,  # 10MB default
+            max_files: int = 5,
+            cleanup_on_init: bool = False,
+            **kwargs):
+        """Initialize the file exporter with the specified output_path and project.
+
+        Args:
+            output_path (str): The path to the output file or directory (if rolling enabled).
+            project (str): The project name for metadata.
+            mode (str): Either "append" or "overwrite". Defaults to "append".
+            enable_rolling (bool): Enable rolling log files. Defaults to False.
+            max_file_size (int): Maximum file size in bytes before rolling. Defaults to 10MB.
+            max_files (int): Maximum number of rolled files to keep. Defaults to 5.
+            cleanup_on_init (bool): Clean up old files during initialization. Defaults to False.
+
+        Raises:
+            ResourceConflictError: If another FileExportMixin instance is already using
+                                 the same file path or would create conflicting files.
+        """
+        self._filepath = Path(output_path)
+        self._project = project
+        self._mode = mode
+        self._enable_rolling = enable_rolling
+        self._max_file_size = max_file_size
+        self._max_files = max_files
+        self._cleanup_on_init = cleanup_on_init
+        self._lock = asyncio.Lock()
+        self._first_write = True
+
+        # Initialize file paths first, then check for conflicts via ResourceConflictMixin
+        self._setup_file_paths()
+
+        # This calls _register_resources() which will check for conflicts
+        super().__init__(*args, **kwargs)
+
+    def _setup_file_paths(self):
+        """Setup file paths using the project name."""
+
+        if self._enable_rolling:
+            # If rolling is enabled, output_path should be a directory
+            self._base_dir = self._filepath if self._filepath.is_dir(
+            ) or not self._filepath.suffix else self._filepath.parent
+            self._base_filename = self._filepath.stem if self._filepath.suffix else f"{self._project}_export"
+            self._file_extension = self._filepath.suffix or ".log"
+            self._base_dir.mkdir(parents=True, exist_ok=True)
+            self._current_file_path = self._base_dir / f"{self._base_filename}{self._file_extension}"
+
+            # Perform initial cleanup if requested
+            if self._cleanup_on_init:
+                self._cleanup_old_files_sync()
+        else:
+            # Traditional single file mode
+            self._filepath.parent.mkdir(parents=True, exist_ok=True)
+            self._current_file_path = self._filepath
+
+            # For single file mode with overwrite, remove existing file
+            if self._mode == FileMode.OVERWRITE and self._cleanup_on_init and self._current_file_path.exists():
+                try:
+                    self._current_file_path.unlink()
+                    logger.info("Cleaned up existing file: %s", self._current_file_path)
+                except OSError as e:
+                    logger.error("Error removing existing file %s: %s", self._current_file_path, e)
+
+    def _get_resource_identifiers(self) -> dict[str, Any]:
+        """Return the file resources this instance will use.
+
+        Returns:
+            dict with file_path and optionally cleanup_pattern for rolling files.
+        """
+        identifiers = {"file_path": str(self._current_file_path.resolve())}
+
+        # Add cleanup pattern for rolling files
+        if self._enable_rolling:
+            cleanup_pattern = f"{self._base_filename}_*{self._file_extension}"
+            pattern_key = f"{self._base_dir.resolve()}:{cleanup_pattern}"
+            identifiers["cleanup_pattern"] = pattern_key
+
+        return identifiers
+
+    def _format_conflict_error(self, resource_type: str, identifier: Any, existing_instance: Any) -> str:
+        """Format user-friendly error messages for file conflicts."""
+        match resource_type:
+            case "file_path":
+                return (f"File path conflict detected: '{self._current_file_path}' is already in use by another "
+                        f"FileExportMixin instance (project: '{existing_instance._project}'). "
+                        f"Use different project names or output paths to avoid conflicts.")
+            case "cleanup_pattern":
+                return (f"Rolling file cleanup conflict detected: Both instances would use pattern "
+                        f"'{self._base_filename}_*{self._file_extension}' in directory '{self._base_dir}', "
+                        f"causing one to delete the other's files. "
+                        f"Current instance (project: '{self._project}'), "
+                        f"existing instance (project: '{existing_instance._project}'). "
+                        f"Use different project names or directories to avoid conflicts.")
+            case _:
+                return f"Unknown file resource conflict: {resource_type} = {identifier}"
+
+    def _cleanup_old_files_sync(self) -> None:
+        """Synchronous version of cleanup for use during initialization."""
+        try:
+            # Find all rolled files matching our pattern
+            pattern = f"{self._base_filename}_*{self._file_extension}"
+            rolled_files = list(self._base_dir.glob(pattern))
+
+            # Sort by modification time (newest first)
+            rolled_files.sort(key=lambda f: f.stat().st_mtime, reverse=True)
+
+            # Remove files beyond max_files limit
+            for old_file in rolled_files[self._max_files:]:
+                try:
+                    old_file.unlink()
+                    logger.info("Cleaned up old log file during init: %s", old_file)
+                except OSError as e:
+                    logger.error("Error removing old file %s: %s", old_file, e)
+
+        except Exception as e:
+            logger.error("Error during initialization cleanup: %s", e)
+
+    async def _should_roll_file(self) -> bool:
+        """Check if the current file should be rolled based on size."""
+        if not self._enable_rolling:
+            return False
+
+        try:
+            if self._current_file_path.exists():
+                stat = self._current_file_path.stat()
+                return stat.st_size >= self._max_file_size
+        except OSError:
+            pass
+        return False
+
+    async def _roll_file(self) -> None:
+        """Roll the current file by renaming it with a timestamp and cleaning up old files."""
+        if not self._current_file_path.exists():
+            return
+
+        # Generate timestamped filename with microsecond precision
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        rolled_filename = f"{self._base_filename}_{timestamp}{self._file_extension}"
+        rolled_path = self._base_dir / rolled_filename
+
+        try:
+            # Rename current file
+            self._current_file_path.rename(rolled_path)
+            logger.info("Rolled log file to: %s", rolled_path)
+
+            # Clean up old files
+            await self._cleanup_old_files()
+
+        except OSError as e:
+            logger.error("Error rolling file %s: %s", self._current_file_path, e)
+
+    async def _cleanup_old_files(self) -> None:
+        """Remove old rolled files beyond the maximum count."""
+        try:
+            # Find all rolled files matching our pattern
+            pattern = f"{self._base_filename}_*{self._file_extension}"
+            rolled_files = list(self._base_dir.glob(pattern))
+
+            # Sort by modification time (newest first)
+            rolled_files.sort(key=lambda f: f.stat().st_mtime, reverse=True)
+
+            # Remove files beyond max_files limit
+            for old_file in rolled_files[self._max_files:]:
+                try:
+                    old_file.unlink()
+                    logger.info("Cleaned up old log file: %s", old_file)
+                except OSError as e:
+                    logger.error("Error removing old file %s: %s", old_file, e)
+
+        except Exception as e:
+            logger.error("Error during cleanup: %s", e)
+
+    async def export_processed(self, item: str | list[str]) -> None:
+        """Export a processed string or list of strings.
+
+        Args:
+            item (str | list[str]): The string or list of strings to export.
+        """
+        try:
+            # Lazy import to avoid slow startup times
+            import aiofiles
+
+            async with self._lock:
+                # Check if we need to roll the file
+                if await self._should_roll_file():
+                    await self._roll_file()
+
+                # Determine file mode
+                if self._first_write and self._mode == FileMode.OVERWRITE:
+                    file_mode = "w"
+                    self._first_write = False
+                else:
+                    file_mode = "a"
+
+                async with aiofiles.open(self._current_file_path, mode=file_mode) as f:
+                    if isinstance(item, list):
+                        # Handle list of strings
+                        for single_item in item:
+                            await f.write(single_item)
+                            await f.write("\n")
+                    else:
+                        # Handle single string
+                        await f.write(item)
+                        await f.write("\n")
+
+        except Exception as e:
+            logger.error("Error exporting event: %s", e, exc_info=True)
+
+    def get_current_file_path(self) -> Path:
+        """Get the current file path being written to.
+
+        Returns:
+            Path: The current file path being written to.
+        """
+        return self._current_file_path
+
+    def get_file_info(self) -> dict:
+        """Get information about the current file and rolling configuration.
+
+        Returns:
+            dict: A dictionary containing the current file path, mode, rolling enabled, cleanup on init,
+                  effective project name, and additional rolling configuration if enabled.
+        """
+        info = {
+            "current_file": str(self._current_file_path),
+            "mode": self._mode,
+            "rolling_enabled": self._enable_rolling,
+            "cleanup_on_init": self._cleanup_on_init,
+            "project": self._project,
+            "effective_project": self._project,
+        }
+
+        if self._enable_rolling:
+            info.update({
+                "max_file_size": self._max_file_size,
+                "max_files": self._max_files,
+                "base_directory": str(self._base_dir),
+            })
+
+            # Add current file size if it exists
+            if self._current_file_path.exists():
+                info["current_file_size"] = self._current_file_path.stat().st_size
+
+        return info