netra-sdk 0.1.31__tar.gz → 0.1.33__tar.gz

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: netra-sdk
-Version: 0.1.31
+Version: 0.1.33
 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
@@ -72,7 +72,7 @@ Requires-Dist: presidio-anonymizer (==2.2.358) ; extra == "presidio"
 Requires-Dist: stanza (>=1.10.1,<2.0.0) ; extra == "presidio"
 Requires-Dist: traceloop-sdk (>=0.40.7,<0.43.0)
 Requires-Dist: transformers (==4.51.3) ; extra == "presidio"
-Project-URL: Bug Tracker, https://github.com/KeyValueSoftwareSystems/netra-sdk-py/issues
+Project-URL: Changelog, https://github.com/KeyValueSoftwareSystems/netra-sdk-py/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/KeyValueSoftwareSystems/netra-sdk-py/blob/main/README.md
 Project-URL: Homepage, https://github.com/KeyValueSoftwareSystems/netra-sdk-py
 Project-URL: Repository, https://github.com/KeyValueSoftwareSystems/netra-sdk-py

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/netra/__init__.py

@@ -1,7 +1,7 @@
 import atexit
 import logging
 import threading
-from typing import Any, Dict, Optional, Set
+from typing import Any, Dict, List, Optional, Set
 
 from opentelemetry import context as context_api
 from opentelemetry import trace
@@ -56,6 +56,8 @@ class Netra:
         enable_root_span: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
+        enable_scrubbing: Optional[bool] = None,
+        blocked_spans: Optional[List[str]] = None,
         instruments: Optional[Set[NetraInstruments]] = None,
         block_instruments: Optional[Set[NetraInstruments]] = None,
     ) -> None:
@@ -77,6 +79,8 @@ class Netra:
                 enable_root_span=enable_root_span,
                 resource_attributes=resource_attributes,
                 environment=environment,
+                enable_scrubbing=enable_scrubbing,
+                blocked_spans=blocked_spans,
             )
 
             # Configure package logging based on debug mode

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/netra/config.py

@@ -1,6 +1,6 @@
 import json
 import os
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from opentelemetry.util.re import parse_env_headers
 
@@ -19,6 +19,8 @@ class Config:
       - 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'})
+      - enable_scrubbing:        Whether to enable pydantic logfire scrubbing; default False (bool)
+      - blocked_spans:           List of span names (prefix/suffix patterns) to block from being exported to the tracing backend
     """
 
     # SDK Constants
@@ -38,6 +40,8 @@ class Config:
         enable_root_span: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
+        enable_scrubbing: Optional[bool] = None,
+        blocked_spans: Optional[List[str]] = None,
     ):
         # Application name: from param, else env
         self.app_name = (
@@ -134,3 +138,14 @@ class Config:
                     self.resource_attributes = {}
             else:
                 self.resource_attributes = {}
+
+        # Enable scrubbing with pydantic logfire? Default False.
+        if enable_scrubbing is not None:
+            self.enable_scrubbing = enable_scrubbing
+        else:
+            env_scrub = os.getenv("NETRA_ENABLE_SCRUBBING")
+            self.enable_scrubbing = True if (env_scrub is not None and env_scrub.lower() in ("1", "true")) else False
+
+        # Blocked span names/prefix patterns
+        if blocked_spans is not None:
+            self.blocked_spans = blocked_spans

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/netra/processors/__init__.py

@@ -1,4 +1,5 @@
 from netra.processors.instrumentation_span_processor import InstrumentationSpanProcessor
+from netra.processors.scrubbing_span_processor import ScrubbingSpanProcessor
 from netra.processors.session_span_processor import SessionSpanProcessor
 
-__all__ = ["SessionSpanProcessor", "InstrumentationSpanProcessor"]
+__all__ = ["SessionSpanProcessor", "InstrumentationSpanProcessor", "ScrubbingSpanProcessor"]

netra_sdk-0.1.33/netra/processors/scrubbing_span_processor.py

@@ -0,0 +1,178 @@
+import logging
+import re
+from typing import Any, Dict, Optional, Union
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.sdk.trace import SpanProcessor
+
+logger = logging.getLogger(__name__)
+
+
+class ScrubbingSpanProcessor(SpanProcessor):  # type: ignore[misc]
+    """OpenTelemetry span processor that scrubs sensitive data from span attributes using pydantic logfire patterns."""
+
+    # Common patterns for sensitive data detection (based on pydantic logfire scrubbing)
+    SENSITIVE_PATTERNS = {
+        # API keys first to avoid other patterns interfering
+        "api_key": re.compile(
+            r"(?:Token:\s*\S{32,})"  # scrub entire "Token: <value>" where value is 32+ non-space
+            r"|(?:sk-[A-Za-z0-9]{16,})"  # scrub only the sk-... token (keep labels like "API Key:")
+        ),
+        "email": re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", re.IGNORECASE),
+        "phone": re.compile(r"(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}"),
+        # Run credit card BEFORE SSN to avoid SSN partially matching inside card numbers
+        "credit_card": re.compile(r"(?<!\d)(?:4\d{15}|5[1-5]\d{14}|3[47]\d{13}|6(?:011|5\d{2})\d{12})(?!\d)"),
+        "ssn": re.compile(r"\b\d{3}-?\d{2}-?\d{4}\b"),
+        "password": re.compile(r"(?i)(?:password|passwd|pwd|secret|token)\s*[:=]\s*\S+"),
+        "bearer_token": re.compile(r"(?i)(?:authorization:\s*)?bearer\s+[A-Za-z0-9\-._~+/]+=*"),
+        "authorization": re.compile(r"(?i)authorization\s*:\s*\S+"),
+    }
+
+    # Sensitive attribute keys that should be scrubbed
+    SENSITIVE_KEYS = {
+        "password",
+        "passwd",
+        "pwd",
+        "secret",
+        "token",
+        "key",
+        "api_key",
+        "auth",
+        "authorization",
+        "bearer",
+        "credential",
+        "private_key",
+        "access_token",
+        "refresh_token",
+        "session_token",
+        "x-api-key",
+        "x-auth-token",
+        "cookie",
+        "set-cookie",
+    }
+
+    def __init__(self):  # type: ignore[no-untyped-def]
+        """Initialize the scrubbing span processor."""
+        self.scrub_replacement = "[SCRUBBED]"
+
+    def on_start(self, span: trace.Span, parent_context: Optional[otel_context.Context] = None) -> None:
+        """Process span when it starts - no scrubbing needed here."""
+
+    def on_end(self, span: trace.Span) -> None:
+        """Scrub sensitive data from span attributes when span ends."""
+        try:
+            # Get span attributes
+            if hasattr(span, "_attributes") and span._attributes:
+                scrubbed_attributes = {}
+                for key, value in span._attributes.items():
+                    scrubbed_key, scrubbed_value = self._scrub_key_value(key, value)
+                    scrubbed_attributes[scrubbed_key] = scrubbed_value
+
+                # Replace the attributes with scrubbed versions
+                span._attributes = scrubbed_attributes
+
+        except Exception as e:
+            logger.exception(f"Error scrubbing span attributes: {e}")
+
+    def _scrub_key_value(self, key: str, value: Any) -> tuple[str, Any]:
+        """Scrub sensitive data from a key-value pair.
+
+        Args:
+            key: The attribute key
+            value: The attribute value
+
+        Returns:
+            Tuple of (scrubbed_key, scrubbed_value)
+        """
+        # Check if key itself is sensitive and value is a simple type (string, number, etc.)
+        if self._is_sensitive_key(key) and not isinstance(value, (dict, list, tuple)):
+            return key, self.scrub_replacement
+
+        # Scrub value based on its type
+        if isinstance(value, str):
+            scrubbed_value = self._scrub_string_value(value)
+            return key, scrubbed_value
+        elif isinstance(value, dict):
+            return key, self._scrub_dict_value(value)
+        elif isinstance(value, (list, tuple)):
+            return key, self._scrub_list_value(value)
+
+        return key, value
+
+    def _is_sensitive_key(self, key: str) -> bool:
+        """Check if a key is considered sensitive.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            True if the key is sensitive, False otherwise
+        """
+        key_lower = key.lower()
+        return any(sensitive_key in key_lower for sensitive_key in self.SENSITIVE_KEYS)
+
+    def _scrub_string_value(self, value: str) -> str:
+        """Scrub sensitive patterns from a string value.
+
+        Args:
+            value: The string value to scrub
+
+        Returns:
+            The scrubbed string value
+        """
+        scrubbed_value = value
+
+        # Early catch-all for contiguous 13-19 digit sequences (credit/debit cards)
+        scrubbed_value = re.sub(r"(?<!\d)\d{13,19}(?!\d)", self.scrub_replacement, scrubbed_value)
+
+        for pattern_name, pattern in self.SENSITIVE_PATTERNS.items():
+            if pattern.search(scrubbed_value):
+                scrubbed_value = pattern.sub(self.scrub_replacement, scrubbed_value)
+
+        # No extra fallback required now that we pre-scrub 13-19 digit sequences
+
+        return scrubbed_value
+
+    def _scrub_dict_value(self, value: Dict[str, Any]) -> Dict[str, Any]:
+        """Recursively scrub sensitive data from a dictionary value.
+
+        Args:
+            value: The dictionary value to scrub
+
+        Returns:
+            The scrubbed dictionary value
+        """
+        scrubbed_dict = {}
+        for k, v in value.items():
+            scrubbed_k, scrubbed_v = self._scrub_key_value(k, v)
+            scrubbed_dict[scrubbed_k] = scrubbed_v
+        return scrubbed_dict
+
+    def _scrub_list_value(self, value: Union[list, tuple]) -> Union[list, tuple] | None:  # type: ignore[type-arg]
+        """Recursively scrub sensitive data from a list/tuple value.
+
+        Args:
+            value: The list/tuple value to scrub
+
+        Returns:
+            The scrubbed list/tuple value
+        """
+        scrubbed_items = []
+        for item in value:
+            if isinstance(item, str):
+                scrubbed_items.append(self._scrub_string_value(item))
+            elif isinstance(item, dict):
+                scrubbed_items.append(self._scrub_dict_value(item))  # type: ignore[arg-type]
+            elif isinstance(item, (list, tuple)):
+                scrubbed_items.append(self._scrub_list_value(item))  # type: ignore[arg-type]
+            else:
+                scrubbed_items.append(item)
+
+        return type(value)(scrubbed_items)
+
+    def force_flush(self, timeout_millis: int = 30000) -> None:
+        """Force flush - no-op for scrubbing processor."""
+
+    def shutdown(self) -> None:
+        """Shutdown - no-op for scrubbing processor."""

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/netra/span_wrapper.py

@@ -4,10 +4,8 @@ import time
 from datetime import datetime
 from typing import Any, Dict, List, Literal, Optional
 
-from opentelemetry import context as context_api
 from opentelemetry import trace
 from opentelemetry.trace import SpanKind, Status, StatusCode
-from opentelemetry.trace.propagation import set_span_in_context
 from pydantic import BaseModel
 
 from netra.config import Config
@@ -72,18 +70,19 @@ class SpanWrapper:
         # OpenTelemetry span management
         self.tracer = trace.get_tracer(module_name)
         self.span: Optional[trace.Span] = None
-        self.context_token: Optional[Any] = None
+        # Internal context manager to manage current-span scope safely
+        self._span_cm: Optional[Any] = None
 
     def __enter__(self) -> "SpanWrapper":
         """Start the span wrapper, begin time tracking, and create OpenTelemetry span."""
         self.start_time = time.time()
 
-        # Create OpenTelemetry span
-        self.span = self.tracer.start_span(name=self.name, kind=SpanKind.CLIENT, attributes=self.attributes)
-
-        # Set span in context
-        ctx = set_span_in_context(self.span)
-        self.context_token = context_api.attach(ctx)
+        # Create OpenTelemetry span and make it current using OTel's context manager
+        # Store the context manager so we can close it in __exit__
+        self._span_cm = self.tracer.start_as_current_span(
+            name=self.name, kind=SpanKind.CLIENT, attributes=self.attributes
+        )
+        self.span = self._span_cm.__enter__()
 
         # Register with SessionManager for name-based lookup
         try:
@@ -93,7 +92,6 @@ class SpanWrapper:
         except Exception:
             logger.exception("Failed to register span '%s' with SessionManager", self.name)
 
-        logger.info(f"Started span wrapper: {self.name}")
         return self
 
     def __exit__(self, exc_type: Optional[type], exc_val: Optional[Exception], exc_tb: Any) -> Literal[False]:
@@ -127,22 +125,19 @@ class SpanWrapper:
             for key, value in self.attributes.items():
                 self.span.set_attribute(key, value)
 
-        # End OpenTelemetry span and detach context
+        # End OpenTelemetry span via the context manager (also clears current context)
         if self.span:
             # Unregister from SessionManager before ending span
             try:
                 SessionManager.unregister_span(self.name, self.span)
             except Exception:
                 logger.exception("Failed to unregister span '%s' from SessionManager", self.name)
-            self.span.end()
-        if self.context_token:
-            context_api.detach(self.context_token)
-
-        logger.info(
-            f"Ended span wrapper: {self.name} (Status: {self.status}, Duration: {duration_ms:.2f}ms)"
-            if duration_ms is not None
-            else f"Ended span wrapper: {self.name} (Status: {self.status})"
-        )
+        if self._span_cm is not None:
+            try:
+                # Delegate to OTel CM to properly end span and restore context
+                self._span_cm.__exit__(exc_type, exc_val, exc_tb)
+            finally:
+                self._span_cm = None
 
         # Don't suppress exceptions
         return False

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/netra/tracer.py

@@ -5,16 +5,18 @@ including exporter setup and span processor configuration.
 """
 
 import logging
-from typing import Any, Dict
+from typing import Any, Dict, List, Sequence
 
 from opentelemetry import trace
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.resources import DEPLOYMENT_ENVIRONMENT, SERVICE_NAME, Resource
-from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
 from opentelemetry.sdk.trace.export import (
     BatchSpanProcessor,
     ConsoleSpanExporter,
     SimpleSpanProcessor,
+    SpanExporter,
+    SpanExportResult,
 )
 
 from netra.config import Config
@@ -22,6 +24,75 @@ from netra.config import Config
 logger = logging.getLogger(__name__)
 
 
+class FilteringSpanExporter(SpanExporter):  # type: ignore[misc]
+    """
+    SpanExporter wrapper that filters out spans by name.
+
+    Matching rules:
+    - Exact match: pattern "Foo" blocks span.name == "Foo".
+    - Prefix match: pattern ending with '*' (e.g., "CloudSpanner.*") blocks spans whose
+      names start with the prefix before '*', e.g., "CloudSpanner.", "CloudSpanner.Query".
+    - Suffix match: pattern starting with '*' (e.g., "*.Query") blocks spans whose
+      names end with the suffix after '*', e.g., "DB.Query", "Search.Query".
+    """
+
+    def __init__(self, exporter: SpanExporter, patterns: Sequence[str]) -> None:
+        self._exporter = exporter
+        # Normalize once for efficient checks
+        exact: List[str] = []
+        prefixes: List[str] = []
+        suffixes: List[str] = []
+        for p in patterns:
+            if not p:
+                continue
+            if p.endswith("*") and not p.startswith("*"):
+                prefixes.append(p[:-1])
+            elif p.startswith("*") and not p.endswith("*"):
+                suffixes.append(p[1:])
+            else:
+                exact.append(p)
+        self._exact = set(exact)
+        self._prefixes = prefixes
+        self._suffixes = suffixes
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        filtered: List[ReadableSpan] = []
+        for s in spans:
+            name = getattr(s, "name", None)
+            if name is None:
+                filtered.append(s)
+                continue
+            if name in self._exact:
+                continue
+            blocked = False
+            for pref in self._prefixes:
+                if name.startswith(pref):
+                    blocked = True
+                    break
+            if not blocked and self._suffixes:
+                for suf in self._suffixes:
+                    if name.endswith(suf):
+                        blocked = True
+                        break
+            if not blocked:
+                filtered.append(s)
+        if not filtered:
+            return SpanExportResult.SUCCESS
+        return self._exporter.export(filtered)
+
+    def shutdown(self) -> None:
+        try:
+            self._exporter.shutdown()
+        except Exception:
+            pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> Any:
+        try:
+            return self._exporter.force_flush(timeout_millis)
+        except Exception:
+            return True
+
+
 class Tracer:
     """
     Configures Netra's OpenTelemetry tracer with OTLP exporter (or Console exporter as fallback)
@@ -65,12 +136,24 @@ class Tracer:
                 endpoint=self._format_endpoint(self.cfg.otlp_endpoint),
                 headers=self.cfg.headers,
             )
+        # Wrap exporter with filtering if blocked span patterns are provided
+        try:
+            patterns = getattr(self.cfg, "blocked_spans", None)
+            if patterns:
+                exporter = FilteringSpanExporter(exporter, patterns)
+                logger.info("Enabled FilteringSpanExporter with %d pattern(s)", len(patterns))
+        except Exception as e:
+            logger.warning("Failed to enable FilteringSpanExporter: %s", e)
         # Add span processors: first instrumentation wrapper, then session processor
-        from netra.processors import InstrumentationSpanProcessor, SessionSpanProcessor
+        from netra.processors import InstrumentationSpanProcessor, ScrubbingSpanProcessor, SessionSpanProcessor
 
         provider.add_span_processor(InstrumentationSpanProcessor())
         provider.add_span_processor(SessionSpanProcessor())
 
+        # Add scrubbing processor if enabled
+        if self.cfg.enable_scrubbing:
+            provider.add_span_processor(ScrubbingSpanProcessor())  # type: ignore[no-untyped-call]
+
         # Install appropriate span processor
         if self.cfg.disable_batch:
             provider.add_span_processor(SimpleSpanProcessor(exporter))

netra_sdk-0.1.33/netra/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.33"

{netra_sdk-0.1.31 → netra_sdk-0.1.33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "netra-sdk"
-version = "0.1.31"
+version = "0.1.33"
 description = "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."
 authors = [
     {name = "Sooraj Thomas",email = "sooraj@keyvalue.systems"}
@@ -83,7 +83,7 @@ dependencies = [
 "Homepage" = "https://github.com/KeyValueSoftwareSystems/netra-sdk-py"
 "Documentation" = "https://github.com/KeyValueSoftwareSystems/netra-sdk-py/blob/main/README.md"
 "Repository" = "https://github.com/KeyValueSoftwareSystems/netra-sdk-py"
-"Bug Tracker" = "https://github.com/KeyValueSoftwareSystems/netra-sdk-py/issues"
+"Changelog" = "https://github.com/KeyValueSoftwareSystems/netra-sdk-py/blob/main/CHANGELOG.md"
 
 [[tool.poetry.packages]]
 include = "netra"

netra_sdk-0.1.31/netra/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.31"