traccia 0.1.2__py3-none-any.whl → 0.1.6__py3-none-any.whl

traccia/tracer/provider.py

@@ -0,0 +1,155 @@
+"""TracerProvider using OpenTelemetry SDK."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, List, Optional
+
+from opentelemetry.sdk.trace import TracerProvider as OTelTracerProvider
+from opentelemetry.sdk.trace import SpanProcessor as OTelSpanProcessor
+from opentelemetry.sdk.resources import Resource as OTelResource
+
+
+class SpanProcessor:
+    """
+    Base span processor interface for Traccia enrichment processors.
+    
+    Enrichment processors run BEFORE span.end() (span is mutable).
+    Export processors use OTel's SpanProcessor interface (run AFTER span.end()).
+    """
+
+    def on_end(self, span) -> None:
+        """
+        Called when a span ends.
+        
+        Note: This is called BEFORE the OTel span ends, so the span is still mutable.
+        You can call span.set_attribute() here.
+        
+        Args:
+            span: Traccia Span instance (mutable)
+        """
+        pass
+
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        pass
+
+    def force_flush(self, timeout: Optional[float] = None) -> None:
+        """Force flush any pending spans."""
+        pass
+
+
+class TracerProvider:
+    """
+    TracerProvider using OpenTelemetry SDK.
+    
+    Separates enrichment processors (Traccia) from export processors (OTel).
+    """
+
+    def __init__(self, resource: Optional[Dict[str, str]] = None) -> None:
+        """
+        Initialize TracerProvider with OpenTelemetry.
+        
+        Args:
+            resource: Resource attributes dictionary (converted to OTel Resource)
+        """
+        # Convert resource dict to OTel Resource
+        otel_resource = OTelResource.create(resource or {})
+        self._otel_provider = OTelTracerProvider(resource=otel_resource)
+        
+        # Store resource as dict for backward compatibility
+        self.resource = resource or {}
+        
+        # Separate enrichment vs export processors
+        self._enrichment_processors: List[SpanProcessor] = []  # Traccia processors
+        self._export_processors: List[OTelSpanProcessor] = []   # OTel processors
+        
+        # Tracers cache
+        self._tracers: Dict[str, Any] = {}
+        self._lock = threading.Lock()
+        
+        # Optional sampler used for head-based sampling at trace start
+        self.sampler: Optional[Any] = None
+
+    def get_tracer(self, name: str) -> "Tracer":
+        """
+        Get a tracer by name.
+        
+        Args:
+            name: Instrumentation scope name
+        
+        Returns:
+            Traccia Tracer instance (wraps OTel Tracer)
+        """
+        with self._lock:
+            tracer = self._tracers.get(name)
+            if tracer is None:
+                from traccia.tracer.tracer import Tracer
+                tracer = Tracer(self, name)
+                self._tracers[name] = tracer
+            return tracer
+
+    def add_span_processor(self, processor: Any) -> None:
+        """
+        Add a span processor.
+        
+        Separates enrichment processors (Traccia) from export processors (OTel).
+        
+        Args:
+            processor: SpanProcessor instance (OTel-compatible or Traccia-compatible)
+        """
+        # If processor is OTel-compatible, add to OTel provider
+        if isinstance(processor, OTelSpanProcessor):
+            self._otel_provider.add_span_processor(processor)
+            self._export_processors.append(processor)
+        else:
+            # Traccia enrichment processor
+            self._enrichment_processors.append(processor)
+
+    def set_sampler(self, sampler: Any) -> None:
+        """
+        Set the sampler.
+        
+        Note: OTel samplers are set at provider creation time.
+        This method stores the sampler for reference but doesn't
+        apply it dynamically. For dynamic sampling, recreate the provider.
+        
+        Args:
+            sampler: Sampler instance
+        """
+        self.sampler = sampler
+        # Note: OTel doesn't support dynamic sampler changes
+        # The sampler would need to be set at provider creation
+
+    def get_sampler(self) -> Optional[Any]:
+        """Get the current sampler."""
+        return self.sampler
+
+    def force_flush(self, timeout: Optional[float] = None) -> None:
+        """Force flush all processors."""
+        # Flush OTel processors
+        self._otel_provider.force_flush(timeout_millis=int(timeout * 1000) if timeout else 30000)
+        
+        # Flush Traccia enrichment processors
+        for processor in self._enrichment_processors:
+            try:
+                processor.force_flush(timeout=timeout)
+            except Exception:
+                pass
+
+    def shutdown(self) -> None:
+        """Shutdown the provider and all processors."""
+        # Shutdown OTel processors
+        self._otel_provider.shutdown()
+        
+        # Shutdown Traccia enrichment processors
+        for processor in self._enrichment_processors:
+            try:
+                processor.shutdown()
+            except Exception:
+                pass
+
+    @property
+    def _otel_tracer_provider(self) -> OTelTracerProvider:
+        """Get the underlying OpenTelemetry TracerProvider."""
+        return self._otel_provider

traccia/tracer/span.py

@@ -0,0 +1,286 @@
+"""Span implementation - minimal wrapper around OpenTelemetry Span."""
+
+from __future__ import annotations
+
+import time
+import traceback
+from enum import Enum
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from opentelemetry.trace import Span as OTelSpan, Status, StatusCode
+from opentelemetry.trace import set_span_in_context
+from opentelemetry import context as context_api
+
+if TYPE_CHECKING:
+    from traccia.tracer.tracer import Tracer
+
+
+class SpanStatus(Enum):
+    UNSET = 0
+    OK = 1
+    ERROR = 2
+
+
+class Span:
+    """
+    Minimal wrapper around OpenTelemetry Span.
+    
+    Provides Traccia API compatibility while using OTel span internally.
+    """
+
+    def __init__(
+        self,
+        otel_span: OTelSpan,
+        tracer: "Tracer",
+        parent_span_id: Optional[str] = None,
+    ) -> None:
+        """
+        Initialize span wrapper.
+        
+        Args:
+            otel_span: OpenTelemetry Span instance
+            tracer: Traccia Tracer instance  
+            parent_span_id: Parent span ID (hex string, for compatibility)
+        """
+        self._otel_span = otel_span
+        self.tracer = tracer
+        self.parent_span_id = parent_span_id
+        self._ended = False
+        self._activation_token = None
+        
+        # Store tracer reference on OTel span for context retrieval
+        otel_span._traccia_tracer = tracer
+        
+        # Create Traccia-compatible properties
+        from traccia.tracer.span_context import SpanContext
+        from traccia.utils.helpers import format_trace_id, format_span_id
+        
+        otel_context = otel_span.get_span_context()
+        self.context = SpanContext(
+            trace_id=format_trace_id(otel_context.trace_id),
+            span_id=format_span_id(otel_context.span_id),
+            trace_flags=1 if otel_context.trace_flags.sampled else 0,
+            trace_state=self._format_trace_state(otel_context.trace_state),
+        )
+        
+        # Enrich tracestate with runtime metadata
+        self._enrich_tracestate()
+        
+        # Expose span properties for processor access
+        self.name = getattr(otel_span, 'name', 'unknown')
+        self.start_time_ns = time.time_ns()
+        self.end_time_ns: Optional[int] = None
+        
+        # Status
+        self.status = SpanStatus.UNSET
+        self.status_description: Optional[str] = None
+        
+        # Maintain attribute dict for easy access
+        # This mirrors OTel span attributes
+        self._attributes: Dict[str, Any] = {}
+
+    def _format_trace_state(self, trace_state) -> Optional[str]:
+        """Format OTel TraceState to W3C string format."""
+        if not trace_state:
+            return None
+        items = []
+        for key, value in trace_state.items():
+            items.append(f"{key}={value}")
+        return ",".join(items) if items else None
+
+    def _enrich_tracestate(self) -> None:
+        """Enrich tracestate with runtime metadata."""
+        try:
+            from traccia.context.propagators import format_tracestate, parse_tracestate
+            from traccia import runtime_config
+            
+            base = parse_tracestate(self.context.trace_state or "")
+            if runtime_config.get_tenant_id():
+                base.setdefault("tenant", runtime_config.get_tenant_id())
+            if runtime_config.get_project_id():
+                base.setdefault("project", runtime_config.get_project_id())
+            if runtime_config.get_debug():
+                base.setdefault("dbg", "1")
+            
+            ts = format_tracestate(base)
+            if ts:
+                from traccia.tracer.span_context import SpanContext
+                self.context = SpanContext(
+                    trace_id=self.context.trace_id,
+                    span_id=self.context.span_id,
+                    trace_flags=self.context.trace_flags,
+                    trace_state=ts,
+                )
+        except Exception:
+            pass
+
+    @property
+    def attributes(self) -> Dict[str, Any]:
+        """
+        Get span attributes (read/write).
+        
+        This property provides direct access to attributes dict.
+        Changes are synced to OTel span via set_attribute().
+        """
+        # Sync from OTel span if available (for processors that read directly)
+        if not self._ended and hasattr(self._otel_span, 'attributes'):
+            try:
+                otel_attrs = getattr(self._otel_span, 'attributes', {})
+                if otel_attrs:
+                    # Merge OTel attributes into local dict
+                    for k, v in otel_attrs.items():
+                        if k not in self._attributes:
+                            self._attributes[k] = v
+            except Exception:
+                pass
+        return self._attributes
+
+    @property
+    def events(self) -> List[Dict[str, Any]]:
+        """Get span events (read-only)."""
+        # OTel doesn't expose events on active span
+        # Return empty list for now
+        return []
+
+    @property
+    def duration_ns(self) -> Optional[int]:
+        """Get span duration in nanoseconds."""
+        if self.end_time_ns is None:
+            return None
+        return self.end_time_ns - self.start_time_ns
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set an attribute on the span."""
+        if self._ended:
+            return
+        
+        # Store in local dict
+        self._attributes[key] = value
+        
+        # Set on OTel span
+        try:
+            self._otel_span.set_attribute(key, value)
+        except Exception:
+            pass
+
+    def add_event(
+        self,
+        name: str,
+        attributes: Optional[Dict[str, Any]] = None,
+        timestamp_ns: Optional[int] = None,
+    ) -> None:
+        """Add an event to the span."""
+        if self._ended:
+            return
+        
+        try:
+            self._otel_span.add_event(
+                name=name,
+                attributes=attributes,
+                timestamp=timestamp_ns,
+            )
+        except Exception:
+            pass
+
+    def record_exception(self, error: BaseException) -> None:
+        """Record an exception event on the span."""
+        if self._ended:
+            return
+        
+        try:
+            self._otel_span.record_exception(error)
+        except Exception:
+            pass
+        
+        self.set_status(SpanStatus.ERROR, str(error))
+
+    def set_status(self, status: SpanStatus, description: Optional[str] = None) -> None:
+        """Set the span status."""
+        if self._ended:
+            return
+        
+        self.status = status
+        self.status_description = description
+        
+        # Convert and set on OTel span
+        if status == SpanStatus.OK:
+            otel_status = Status(status_code=StatusCode.OK, description=description)
+        elif status == SpanStatus.ERROR:
+            otel_status = Status(status_code=StatusCode.ERROR, description=description)
+        else:
+            otel_status = Status(status_code=StatusCode.UNSET, description=description)
+        
+        try:
+            self._otel_span.set_status(otel_status)
+        except Exception:
+            pass
+
+    def end(self) -> None:
+        """
+        End the span.
+        
+        Enrichment processors run BEFORE span.end() (span is still mutable).
+        Export processors run AFTER span.end() (OTel handles this automatically).
+        """
+        if self._ended:
+            return
+        
+        self.end_time_ns = time.time_ns()
+        if self.status == SpanStatus.UNSET:
+            self.status = SpanStatus.OK
+            # Set status on OTel span as well
+            try:
+                from opentelemetry.trace import Status, StatusCode
+                self._otel_span.set_status(Status(status_code=StatusCode.OK))
+            except Exception:
+                pass
+        
+        # 1. Run enrichment processors (span is still mutable)
+        self.tracer._run_enrichment_processors(self)
+        
+        # 2. End the OTel span (makes it immutable)
+        try:
+            self._otel_span.end(end_time=self.end_time_ns)
+        except Exception:
+            pass
+        
+        # 3. OTel export processors run automatically on ReadableSpan
+        
+        self._ended = True
+
+    # Context manager support
+    def __enter__(self) -> "Span":
+        """Enter context manager."""
+        ctx = set_span_in_context(self._otel_span)
+        self._activation_token = context_api.attach(ctx)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        """Exit context manager."""
+        try:
+            if exc:
+                self.record_exception(exc)
+            self.end()
+        finally:
+            if self._activation_token:
+                context_api.detach(self._activation_token)
+                self._activation_token = None
+        return False
+
+    async def __aenter__(self) -> "Span":
+        """Enter async context manager."""
+        ctx = set_span_in_context(self._otel_span)
+        self._activation_token = context_api.attach(ctx)
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        """Exit async context manager."""
+        try:
+            if exc:
+                self.record_exception(exc)
+            self.end()
+        finally:
+            if self._activation_token:
+                context_api.detach(self._activation_token)
+                self._activation_token = None
+        return False

traccia/tracer/span_context.py

@@ -0,0 +1,16 @@
+"""Immutable trace metadata."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class SpanContext:
+    trace_id: str
+    span_id: str
+    trace_flags: int = 1  # 1 = sampled, 0 = not sampled
+    trace_state: Optional[str] = None
+
+    def is_valid(self) -> bool:
+        return bool(self.trace_id and self.span_id)
+

traccia/tracer/tracer.py

@@ -0,0 +1,243 @@
+"""Tracer using OpenTelemetry SDK with Traccia API compatibility."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from opentelemetry.trace import Tracer as OTelTracer
+from opentelemetry.trace import set_span_in_context
+from opentelemetry import context as context_api
+
+from traccia import runtime_config
+
+
+class Tracer:
+    """
+    Tracer wrapper that uses OpenTelemetry Tracer internally.
+    
+    Maintains Traccia API compatibility while using OTel underneath.
+    """
+
+    def __init__(self, provider: "TracerProvider", instrumentation_scope: str):
+        """
+        Initialize tracer with OpenTelemetry Tracer.
+        
+        Args:
+            provider: Traccia TracerProvider instance
+            instrumentation_scope: Instrumentation scope name
+        """
+        self._provider = provider
+        self.instrumentation_scope = instrumentation_scope
+        
+        # Get OTel tracer from provider's OTel provider
+        self._otel_tracer: OTelTracer = provider._otel_provider.get_tracer(instrumentation_scope)
+
+    def start_span(
+        self,
+        name: str,
+        attributes: Optional[Dict[str, Any]] = None,
+        parent: Optional[Any] = None,
+        parent_context: Optional[Any] = None,
+    ) -> "Span":
+        """
+        Start a new span.
+        
+        Args:
+            name: Span name
+            attributes: Optional attributes dictionary
+            parent: Optional parent span
+            parent_context: Optional parent span context
+        
+        Returns:
+            Traccia Span instance (wraps OTel Span)
+        """
+        from opentelemetry.trace import get_current_span
+        
+        # Determine parent context
+        otel_parent_context = None
+        parent_span_id = None
+        
+        if parent:
+            # Extract parent span ID for Traccia compatibility
+            if hasattr(parent, 'context'):
+                parent_span_id = parent.context.span_id
+            
+            # Get OTel span from parent
+            if hasattr(parent, '_otel_span'):
+                otel_parent_context = set_span_in_context(parent._otel_span)
+            elif hasattr(parent, 'get_span_context'):
+                # Direct OTel span
+                otel_parent_context = set_span_in_context(parent)
+                from traccia.utils.helpers import format_span_id
+                parent_span_id = format_span_id(parent.get_span_context().span_id)
+        
+        elif parent_context:
+            # Convert Traccia SpanContext to OTel context
+            if hasattr(parent_context, 'trace_id'):
+                from traccia.utils.helpers import parse_trace_id, parse_span_id
+                from opentelemetry.trace import SpanContext as OTelSpanContext, TraceFlags, TraceState, NonRecordingSpan
+                
+                trace_id = parse_trace_id(parent_context.trace_id)
+                span_id = parse_span_id(parent_context.span_id)
+                trace_flags = TraceFlags(parent_context.trace_flags)
+                
+                # Parse trace_state
+                trace_state = None
+                if parent_context.trace_state:
+                    from traccia.context.propagators import parse_tracestate
+                    parsed = parse_tracestate(parent_context.trace_state)
+                    if parsed:
+                        items = [(k, v) for k, v in parsed.items()]
+                        trace_state = TraceState(items)
+                
+                otel_span_context = OTelSpanContext(
+                    trace_id=trace_id,
+                    span_id=span_id,
+                    is_remote=False,
+                    trace_flags=trace_flags,
+                    trace_state=trace_state or TraceState(),
+                )
+                otel_parent_context = set_span_in_context(NonRecordingSpan(otel_span_context))
+                parent_span_id = parent_context.span_id
+        
+        # If no parent specified, use current span
+        if otel_parent_context is None:
+            current_span = get_current_span()
+            if current_span and current_span.get_span_context().is_valid:
+                otel_parent_context = set_span_in_context(current_span)
+                from traccia.utils.helpers import format_span_id
+                parent_span_id = format_span_id(current_span.get_span_context().span_id)
+        
+        # Handle sampling
+        sampler = getattr(self._provider, "sampler", None)
+        if sampler and otel_parent_context is None:
+            # New root trace - check sampler
+            try:
+                sampled = bool(sampler.should_sample().sampled)
+                if not sampled:
+                    # Create a non-recording span for unsampled traces
+                    from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
+                    from opentelemetry.trace.id_generator import RandomIdGenerator
+                    
+                    id_generator = RandomIdGenerator()
+                    trace_id = id_generator.generate_trace_id()
+                    span_id = id_generator.generate_span_id()
+                    
+                    unsampled_context = SpanContext(
+                        trace_id=trace_id,
+                        span_id=span_id,
+                        is_remote=False,
+                        trace_flags=TraceFlags(0),  # Not sampled
+                    )
+                    unsampled_span = NonRecordingSpan(unsampled_context)
+                    otel_parent_context = set_span_in_context(unsampled_span)
+            except Exception:
+                pass
+        
+        # Debug override: if enabled, force sampling for new traces
+        if otel_parent_context is None and runtime_config.get_debug():
+            pass  # OTel will handle this
+        
+        # Check for auto-trace conflict
+        self._check_auto_trace_conflict(name, otel_parent_context)
+        
+        # Start OTel span
+        otel_span = self._otel_tracer.start_span(
+            name=name,
+            attributes=attributes,
+            context=otel_parent_context,
+        )
+        
+        # Wrap in Traccia Span
+        from traccia.tracer.span import Span
+        return Span(otel_span, self, parent_span_id)
+
+    def start_as_current_span(
+        self,
+        name: str,
+        attributes: Optional[Dict[str, Any]] = None,
+        parent: Optional[Any] = None,
+        parent_context: Optional[Any] = None,
+    ) -> "Span":
+        """
+        Start a span and set it as current (context manager).
+        
+        Args:
+            name: Span name
+            attributes: Optional attributes dictionary
+            parent: Optional parent span
+            parent_context: Optional parent span context
+        
+        Returns:
+            Traccia Span instance (wraps OTel Span)
+        """
+        return self.start_span(
+            name=name,
+            attributes=attributes,
+            parent=parent,
+            parent_context=parent_context,
+        )
+
+    def get_current_span(self) -> Optional["Span"]:
+        """Get the current span."""
+        from opentelemetry.trace import get_current_span
+        otel_span = get_current_span()
+        if otel_span and otel_span.get_span_context().is_valid:
+            from traccia.tracer.span import Span
+            # Check if we already have a Traccia wrapper
+            if hasattr(otel_span, '_traccia_tracer'):
+                # Try to return existing wrapper (best effort)
+                pass
+            return Span(otel_span, self)
+        return None
+    
+    def _check_auto_trace_conflict(self, span_name: str, parent_context: Optional[Any]) -> None:
+        """
+        Check if user is creating a span with 'root' in name while auto-trace is active.
+        
+        Logs an informational warning if a conflict is detected.
+        
+        Args:
+            span_name: Name of the span being created
+            parent_context: Parent context (if None, this might be a root span)
+        """
+        # Import here to avoid circular dependency
+        from traccia import auto
+        
+        # Only warn if auto-trace is active
+        if not auto._auto_trace_context:
+            return
+        
+        # Only warn if span name is exactly "root" (case-insensitive) to avoid false positives
+        # This helps users who might be migrating from manual root span creation
+        if span_name.lower() != "root":
+            return
+        
+        # Only warn if this would be a root span (no parent context)
+        # Note: If parent_context exists, this is a child span and that's expected
+        if parent_context is not None:
+            return
+        
+        import logging
+        logger = logging.getLogger(__name__)
+        logger.debug(
+            f"Auto-started trace '{auto._auto_trace_name}' is active. "
+            f"Created span '{span_name}' will be a child of the auto-started trace. "
+            f"Use traccia.end_auto_trace() if you want a separate trace."
+        )
+
+    def _run_enrichment_processors(self, span: "Span") -> None:
+        """
+        Run enrichment processors before span ends.
+        
+        Called by Span.end() before the OTel span is ended.
+        
+        Args:
+            span: Traccia Span instance (still mutable)
+        """
+        for processor in self._provider._enrichment_processors:
+            try:
+                processor.on_end(span)
+            except Exception:
+                # Processors should not crash tracing
+                pass