netra-sdk 0.1.28__py3-none-any.whl → 0.1.29__py3-none-any.whl

netra/__init__.py

@@ -1,7 +1,12 @@
+import atexit
 import logging
 import threading
 from typing import Any, Dict, Optional, Set
 
+from opentelemetry import context as context_api
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind
+
 from netra.instrumentation.instruments import InstrumentSet, NetraInstruments
 
 from .config import Config
@@ -27,6 +32,8 @@ class Netra:
     _initialized = False
     # Use RLock so the thread that already owns the lock can re-acquire it safely
     _init_lock = threading.RLock()
+    _root_span = None
+    _root_ctx_token = None
 
     @classmethod
     def is_initialized(cls) -> bool:
@@ -46,6 +53,7 @@ class Netra:
         disable_batch: Optional[bool] = None,
         trace_content: Optional[bool] = None,
         debug_mode: Optional[bool] = None,
+        enable_root_span: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
         instruments: Optional[Set[NetraInstruments]] = None,
@@ -66,6 +74,7 @@ class Netra:
                 disable_batch=disable_batch,
                 trace_content=trace_content,
                 debug_mode=debug_mode,
+                enable_root_span=enable_root_span,
                 resource_attributes=resource_attributes,
                 environment=environment,
             )
@@ -106,6 +115,61 @@ class Netra:
             cls._initialized = True
             logger.info("Netra successfully initialized.")
 
+            # Create and attach a long-lived root span if enabled
+            if cfg.enable_root_span:
+                tracer = trace.get_tracer("netra.root.span")
+                root_name = f"{Config.LIBRARY_NAME}.root.span"
+                root_span = tracer.start_span(root_name, kind=SpanKind.INTERNAL)
+                # Add useful attributes
+                if cfg.app_name:
+                    root_span.set_attribute("service.name", cfg.app_name)
+                root_span.set_attribute("netra.environment", cfg.environment)
+                root_span.set_attribute("netra.library.version", Config.LIBRARY_VERSION)
+
+                # Attach span to current context so subsequent spans become its children
+                ctx = trace.set_span_in_context(root_span)
+                token = context_api.attach(ctx)
+
+                # Save for potential shutdown/cleanup and session tracking
+                cls._root_span = root_span
+                cls._root_ctx_token = token
+                try:
+                    SessionManager.set_current_span(root_span)
+                except Exception:
+                    pass
+                logger.info("Netra root span created and attached to context.")
+
+                # Ensure cleanup at process exit
+                atexit.register(cls.shutdown)
+
+    @classmethod
+    def shutdown(cls) -> None:
+        """Optional cleanup to end the root span and detach context."""
+        with cls._init_lock:
+            if cls._root_ctx_token is not None:
+                try:
+                    context_api.detach(cls._root_ctx_token)
+                except Exception:
+                    pass
+                finally:
+                    cls._root_ctx_token = None
+            if cls._root_span is not None:
+                try:
+                    cls._root_span.end()
+                except Exception:
+                    pass
+                finally:
+                    cls._root_span = None
+            # Try to flush and shutdown the tracer provider to ensure export
+            try:
+                provider = trace.get_tracer_provider()
+                if hasattr(provider, "force_flush"):
+                    provider.force_flush()
+                if hasattr(provider, "shutdown"):
+                    provider.shutdown()
+            except Exception:
+                pass
+
     @classmethod
     def set_session_id(cls, session_id: str) -> None:
         """

netra/config.py

@@ -17,6 +17,7 @@ class Config:
       - disable_batch:           Whether to disable batch span processor (bool)
       - trace_content:           Whether to capture prompt/completion content (bool)
       - debug_mode:              Whether to enable SDK logging; default False (bool)
+      - enable_root_span:        Whether to create a process root span; default False (bool)
       - resource_attributes:     Custom resource attributes dict (e.g., {'env': 'prod', 'version': '1.0.0'})
     """
 
@@ -32,6 +33,7 @@ class Config:
         disable_batch: Optional[bool] = None,
         trace_content: Optional[bool] = None,
         debug_mode: Optional[bool] = None,
+        enable_root_span: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
     ):
@@ -106,6 +108,13 @@ class Config:
         else:
             self.environment = os.getenv("NETRA_ENV", "local")
 
+        # Enable a long-lived root span for the process? Default False.
+        if enable_root_span is not None:
+            self.enable_root_span = enable_root_span
+        else:
+            env_root = os.getenv("NETRA_ENABLE_ROOT_SPAN")
+            self.enable_root_span = True if (env_root is not None and env_root.lower() in ("1", "true")) else False
+
         # Resource attributes: param override, else parse JSON from env, else empty dict
         if resource_attributes is not None:
             self.resource_attributes = resource_attributes

netra/version.py

@@ -1 +1 @@
-__version__ = "0.1.28"
+__version__ = "0.1.29"

{netra_sdk-0.1.28.dist-info → netra_sdk-0.1.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: netra-sdk
-Version: 0.1.28
+Version: 0.1.29
 Summary: A Python SDK for AI application observability that provides OpenTelemetry-based monitoring, tracing, and PII protection for LLM and vector database applications. Enables easy instrumentation, session tracking, and privacy-focused data collection for AI systems in production environments.
 License: Apache-2.0
 Keywords: netra,tracing,observability,sdk,ai,llm,vector,database

{netra_sdk-0.1.28.dist-info → netra_sdk-0.1.29.dist-info}/RECORD

@@ -1,9 +1,9 @@
-netra/__init__.py,sha256=hboj9svp8pHeMk59ifwyNgXNElaHvTEpUKhjD1-1azU,6997
+netra/__init__.py,sha256=EIMbq0ycEIolmyk7uGXkmgvydfWArNk-soBIEQijsiY,9612
 netra/anonymizer/__init__.py,sha256=KeGPPZqKVZbtkbirEKYTYhj6aZHlakjdQhD7QHqBRio,133
 netra/anonymizer/anonymizer.py,sha256=IcrYkdwWrFauGWUeAW-0RwrSUM8VSZCFNtoywZhvIqU,3778
 netra/anonymizer/base.py,sha256=ytPxHCUD2OXlEY6fNTuMmwImNdIjgj294I41FIgoXpU,5946
 netra/anonymizer/fp_anonymizer.py,sha256=_6svIYmE0eejdIMkhKBUWCNjGtGimtrGtbLvPSOp8W4,6493
-netra/config.py,sha256=MiJXqQ1GntU9U4MyzZnQ38Lma0EE96Tx1l5wH3rTrus,5452
+netra/config.py,sha256=zmTssfUExG8viSMKN9Yfd8i--7S4oUQT8IyvwAI4C2U,5950
 netra/decorators.py,sha256=TqORBs0Xv_CZHOAwrWkpvscMj4FgOJsgo1CRYoG6C7Y,7435
 netra/exceptions/__init__.py,sha256=uDgcBxmC4WhdS7HRYQk_TtJyxH1s1o6wZmcsnSHLAcM,174
 netra/exceptions/injection.py,sha256=ke4eUXRYUFJkMZgdSyPPkPt5PdxToTI6xLEBI0hTWUQ,1332
@@ -43,8 +43,8 @@ netra/scanner.py,sha256=kyDpeZiscCPb6pjuhS-sfsVj-dviBFRepdUWh0sLoEY,11554
 netra/session_manager.py,sha256=Ks8A6B9RYe0tV8PeWYuN0M-UMZqa47uquuw6D7C1vCE,6701
 netra/span_wrapper.py,sha256=ec2WLYTRLZ02WSSCYEsMn1PgUGVji9rFyq_CRCV9rog,7388
 netra/tracer.py,sha256=In5QPVLz_6BxrolWpav9EuR9_hirD2UUIlyY75QUaKk,3450
-netra/version.py,sha256=MWZDdAHrdUZS0c3VlLqX4O1eaxPodI7irMtEvknKQ94,23
-netra_sdk-0.1.28.dist-info/LICENCE,sha256=8B_UoZ-BAl0AqiHAHUETCgd3I2B9yYJ1WEQtVb_qFMA,11359
-netra_sdk-0.1.28.dist-info/METADATA,sha256=T63YlGVzQCx6cxKp8fXMK136IYwpcFC5VOUeLTKg_8E,28151
-netra_sdk-0.1.28.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-netra_sdk-0.1.28.dist-info/RECORD,,
+netra/version.py,sha256=A-lFHZ4YpCrWZ6nw3tlt_yurFJ00mInm3gR6hz51Eww,23
+netra_sdk-0.1.29.dist-info/LICENCE,sha256=8B_UoZ-BAl0AqiHAHUETCgd3I2B9yYJ1WEQtVb_qFMA,11359
+netra_sdk-0.1.29.dist-info/METADATA,sha256=XKGT69ygEEA6hbSinO1heKikakeIngiMqotgwQbFyeQ,28151
+netra_sdk-0.1.29.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+netra_sdk-0.1.29.dist-info/RECORD,,