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

traccia/context/__init__.py

@@ -0,0 +1,33 @@
+"""Context utilities for the tracing SDK."""
+
+from traccia.context.context import get_current_span, pop_span, push_span
+from traccia.context.propagators import (
+    extract_trace_context,
+    extract_tracestate,
+    extract_traceparent,
+    format_traceparent,
+    format_tracestate,
+    inject_traceparent,
+    inject_tracestate,
+    parse_tracestate,
+    parse_traceparent,
+    inject,
+    extract,
+)
+
+__all__ = [
+    "get_current_span",
+    "push_span",
+    "pop_span",
+    "format_traceparent",
+    "inject_traceparent",
+    "parse_traceparent",
+    "extract_traceparent",
+    "format_tracestate",
+    "parse_tracestate",
+    "inject_tracestate",
+    "extract_tracestate",
+    "extract_trace_context",
+    "inject",
+    "extract",
+]

traccia/context/context.py

@@ -0,0 +1,67 @@
+"""Context helpers for managing the active span stack - using OpenTelemetry directly."""
+
+from contextvars import Token
+from typing import Optional, TYPE_CHECKING
+
+from opentelemetry.trace import get_current_span as otel_get_current_span
+from opentelemetry.trace import set_span_in_context
+from opentelemetry import context as context_api
+
+if TYPE_CHECKING:
+    from traccia.tracer.span import Span
+
+
+def get_current_span() -> Optional["Span"]:
+    """
+    Return the currently active span, if any.
+    
+    Uses OpenTelemetry's context API internally.
+    """
+    otel_span = otel_get_current_span()
+    if otel_span and otel_span.get_span_context().is_valid:
+        # Get tracer from span if available
+        try:
+            if hasattr(otel_span, '_traccia_tracer'):
+                tracer = otel_span._traccia_tracer
+            else:
+                # Fallback: create a tracer from global provider
+                from traccia import get_tracer_provider
+                provider = get_tracer_provider()
+                tracer = provider.get_tracer("context")
+            
+            # Wrap in Traccia Span
+            from traccia.tracer.span import Span
+            return Span(otel_span, tracer)
+        except Exception:
+            # If wrapping fails, return None
+            return None
+    return None
+
+
+def push_span(span: "Span") -> Token:
+    """
+    Push a span onto the context and set it as current.
+    
+    Uses OpenTelemetry's context API internally.
+    
+    Returns:
+        Token needed to restore the previous state
+    """
+    if hasattr(span, '_otel_span'):
+        otel_span = span._otel_span
+    else:
+        otel_span = span
+    
+    ctx = set_span_in_context(otel_span)
+    token = context_api.attach(ctx)
+    return token
+
+
+def pop_span(token: Token) -> None:
+    """
+    Restore the previous span context using the provided token.
+    
+    Args:
+        token: Token returned by push_span()
+    """
+    context_api.detach(token)

traccia/context/propagators.py

@@ -0,0 +1,283 @@
+"""W3C trace context propagation using OpenTelemetry's standard propagators."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Any
+
+from opentelemetry.propagate import inject as otel_inject, extract as otel_extract
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.trace import get_current_span, set_span_in_context
+from opentelemetry.trace import SpanContext as OTelSpanContext, TraceFlags, TraceState
+from opentelemetry.trace import NonRecordingSpan
+from opentelemetry import context as context_api
+
+from traccia.tracer.span_context import SpanContext
+from traccia.utils.helpers import format_trace_id, format_span_id, parse_trace_id, parse_span_id
+
+# Use OTel's W3C Trace Context propagator
+_propagator = TraceContextTextMapPropagator()
+
+
+def format_traceparent(context: SpanContext) -> str:
+    """
+    Format traceparent header value (W3C Trace Context standard).
+    
+    Uses OpenTelemetry's propagator internally.
+    """
+    # Convert Traccia SpanContext to OTel SpanContext
+    otel_context = _traccia_to_otel_context(context)
+    
+    # Create a non-recording span with the context
+    span = NonRecordingSpan(otel_context)
+    ctx = set_span_in_context(span)
+    
+    # Create a carrier dict and inject
+    carrier: Dict[str, str] = {}
+    _propagator.inject(carrier, context=ctx)
+    
+    # Extract traceparent from carrier
+    return carrier.get("traceparent", "")
+
+
+def format_tracestate(state: Dict[str, str]) -> str:
+    """
+    Format tracestate header value from a dict.
+    
+    Formats according to W3C Trace Context standard.
+    """
+    if not state:
+        return ""
+    
+    # Format manually (W3C format: key1=value1,key2=value2)
+    items = []
+    for k, v in state.items():
+        # Sanitize key and value
+        key = str(k).strip().lower()[:256]
+        value = str(v).strip().replace(",", "_").replace("=", "_")[:256]
+        if key and value:
+            items.append(f"{key}={value}")
+    
+    return ",".join(items)
+
+
+def parse_tracestate(header_value: str) -> Dict[str, str]:
+    """
+    Parse a tracestate header into a dict.
+    
+    Parses W3C Trace Context tracestate format: key1=value1,key2=value2
+    """
+    if not header_value:
+        return {}
+    
+    result = {}
+    for item in header_value.split(","):
+        item = item.strip()
+        if not item or "=" not in item:
+            continue
+        parts = item.split("=", 1)
+        if len(parts) == 2:
+            key = parts[0].strip().lower()
+            value = parts[1].strip()
+            if key and value:
+                result[key] = value
+    
+    return result
+
+
+def parse_traceparent(header_value: str) -> Optional[SpanContext]:
+    """
+    Parse a traceparent header into a SpanContext.
+    
+    Uses OpenTelemetry's W3C Trace Context parser.
+    """
+    if not header_value:
+        return None
+    
+    # Use OTel to parse traceparent
+    carrier = {"traceparent": header_value}
+    ctx = _propagator.extract(carrier)
+    
+    # Get span context from OTel context
+    span = get_current_span(context=ctx)
+    if span:
+        otel_context = span.get_span_context()
+        if otel_context.is_valid:
+            return _otel_to_traccia_context(otel_context)
+    
+    return None
+
+
+def inject_traceparent(headers: Dict[str, str], context: SpanContext) -> None:
+    """
+    Inject traceparent header into headers dict.
+    
+    Uses OpenTelemetry's inject() function.
+    """
+    # Convert Traccia context to OTel context
+    otel_context = _traccia_to_otel_context(context)
+    
+    # Create OTel context with span
+    span = NonRecordingSpan(otel_context)
+    ctx = set_span_in_context(span)
+    
+    # Inject using OTel
+    _propagator.inject(carrier=headers, context=ctx)
+
+
+def inject_tracestate(headers: Dict[str, str], context: SpanContext) -> None:
+    """
+    Inject tracestate header if present on the context.
+    
+    Uses OpenTelemetry's inject() function.
+    """
+    if not context.trace_state:
+        return
+    
+    # Parse tracestate and create OTel TraceState
+    parsed = parse_tracestate(context.trace_state)
+    if parsed:
+        trace_state = TraceState([(k, v) for k, v in parsed.items()])
+        
+        # Convert Traccia context to OTel context with tracestate
+        otel_context = _traccia_to_otel_context(context)
+        # Update trace_state
+        otel_context = OTelSpanContext(
+            trace_id=otel_context.trace_id,
+            span_id=otel_context.span_id,
+            is_remote=otel_context.is_remote,
+            trace_flags=otel_context.trace_flags,
+            trace_state=trace_state,
+        )
+        
+        # Create span with context and inject
+        span = NonRecordingSpan(otel_context)
+        ctx = set_span_in_context(span)
+        _propagator.inject(carrier=headers, context=ctx)
+
+
+def extract_traceparent(headers: Dict[str, str]) -> Optional[SpanContext]:
+    """
+    Extract traceparent header from headers and parse it.
+    
+    Uses OpenTelemetry's extract() function.
+    """
+    # Use OTel to extract
+    ctx = _propagator.extract(carrier=headers)
+    
+    # Get span from context
+    span = get_current_span(context=ctx)
+    if span:
+        otel_context = span.get_span_context()
+        if otel_context.is_valid:
+            return _otel_to_traccia_context(otel_context)
+    
+    return None
+
+
+def extract_tracestate(headers: Dict[str, str]) -> Optional[str]:
+    """
+    Extract tracestate header value (case-insensitive).
+    
+    Returns the raw tracestate string.
+    """
+    # Case-insensitive lookup
+    for key, value in headers.items():
+        if key.lower() == "tracestate":
+            return value
+    return None
+
+
+def extract_trace_context(headers: Dict[str, str]) -> Optional[SpanContext]:
+    """
+    Extract both traceparent and tracestate and return a combined SpanContext.
+    
+    Uses OpenTelemetry's extract() function.
+    """
+    # Use OTel to extract both
+    ctx = _propagator.extract(carrier=headers)
+    
+    # Get span from context
+    span = get_current_span(context=ctx)
+    if span:
+        otel_context = span.get_span_context()
+        if otel_context.is_valid:
+            # Extract tracestate separately
+            tracestate_str = extract_tracestate(headers)
+            return _otel_to_traccia_context(otel_context, tracestate_str)
+    
+    return None
+
+
+# Helper functions for context conversion
+
+def _traccia_to_otel_context(traccia_context: SpanContext) -> OTelSpanContext:
+    """Convert Traccia SpanContext to OTel SpanContext."""
+    trace_id = parse_trace_id(traccia_context.trace_id)
+    span_id = parse_span_id(traccia_context.span_id)
+    trace_flags = TraceFlags(traccia_context.trace_flags)
+    
+    # Parse trace_state
+    trace_state = TraceState()
+    if traccia_context.trace_state:
+        parsed = parse_tracestate(traccia_context.trace_state)
+        if parsed:
+            items = [(k, v) for k, v in parsed.items()]
+            trace_state = TraceState(items)
+    
+    return OTelSpanContext(
+        trace_id=trace_id,
+        span_id=span_id,
+        is_remote=False,
+        trace_flags=trace_flags,
+        trace_state=trace_state,
+    )
+
+
+def _otel_to_traccia_context(otel_context: OTelSpanContext, tracestate_str: Optional[str] = None) -> SpanContext:
+    """Convert OTel SpanContext to Traccia 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
+    
+    # Format trace_state
+    trace_state = None
+    if tracestate_str:
+        trace_state = tracestate_str
+    elif otel_context.trace_state:
+        # Format OTel TraceState to string
+        items = []
+        for key, value in otel_context.trace_state.items():
+            items.append(f"{key}={value}")
+        if items:
+            trace_state = ",".join(items)
+    
+    return SpanContext(
+        trace_id=trace_id,
+        span_id=span_id,
+        trace_flags=trace_flags,
+        trace_state=trace_state,
+    )
+
+
+# Additional helper: inject/extract using OTel's standard API
+
+def inject(carrier: Dict[str, str], context: Optional[Any] = None) -> None:
+    """
+    Inject trace context into carrier using OpenTelemetry's standard API.
+    
+    This is a convenience function that uses OTel's inject() directly.
+    If context is not provided, uses current context.
+    """
+    if context is None:
+        otel_inject(carrier)
+    else:
+        otel_inject(carrier, context=context)
+
+
+def extract(carrier: Dict[str, str]) -> Any:
+    """
+    Extract trace context from carrier using OpenTelemetry's standard API.
+    
+    Returns OTel context that can be used with start_span().
+    """
+    return otel_extract(carrier)

traccia/errors.py

@@ -0,0 +1,48 @@
+"""Traccia SDK error hierarchy and exceptions."""
+
+from __future__ import annotations
+
+
+class TracciaError(Exception):
+    """Base exception for all Traccia SDK errors."""
+    
+    def __init__(self, message: str, details: dict = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+    
+    def __str__(self) -> str:
+        if self.details:
+            details_str = ", ".join(f"{k}={v}" for k, v in self.details.items())
+            return f"{self.message} ({details_str})"
+        return self.message
+
+
+class ConfigError(TracciaError):
+    """Raised when configuration is invalid or conflicting."""
+    pass
+
+
+class ValidationError(TracciaError):
+    """Raised when validation fails."""
+    pass
+
+
+class ExportError(TracciaError):
+    """Raised when span export fails."""
+    pass
+
+
+class RateLimitError(TracciaError):
+    """Raised when rate limit is exceeded (in strict mode)."""
+    pass
+
+
+class InitializationError(TracciaError):
+    """Raised when SDK initialization fails."""
+    pass
+
+
+class InstrumentationError(TracciaError):
+    """Raised when instrumentation/patching fails."""
+    pass

traccia/exporter/__init__.py

@@ -0,0 +1,8 @@
+"""Exporters for delivering spans to backends."""
+
+from traccia.exporter.http_exporter import HttpExporter
+from traccia.exporter.console_exporter import ConsoleExporter
+from traccia.exporter.file_exporter import FileExporter
+from traccia.exporter.otlp_exporter import OTLPExporter
+
+__all__ = ["HttpExporter", "ConsoleExporter", "FileExporter", "OTLPExporter"]

traccia/exporter/console_exporter.py

@@ -0,0 +1,31 @@
+"""Console exporter for developer visibility."""
+
+from __future__ import annotations
+
+import sys
+from typing import Iterable
+
+from traccia.tracer.span import Span
+
+
+class ConsoleExporter:
+    """Simple exporter that prints spans to stdout (or provided stream)."""
+
+    def __init__(self, stream=None) -> None:
+        self.stream = stream or sys.stdout
+
+    def export(self, spans: Iterable[Span]) -> bool:
+        for span in spans:
+            line = (
+                f"[span] name={span.name} trace_id={span.context.trace_id} "
+                f"span_id={span.context.span_id} status={span.status.name} "
+                f"duration_ns={span.duration_ns}"
+            )
+            if span.attributes:
+                line += f" attrs={span.attributes}"
+            print(line, file=self.stream)
+        return True
+
+    def shutdown(self) -> None:
+        return None
+

traccia/exporter/file_exporter.py

@@ -0,0 +1,178 @@
+"""File exporter for writing traces to a JSON file."""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any, Dict, Iterable, List
+
+from traccia.tracer.span import Span
+from traccia.tracer.span import SpanStatus
+from traccia import runtime_config
+
+
+class FileExporter:
+    """
+    Exporter that writes spans to a JSON file in JSONL format.
+    
+    Each export() call writes one JSON object (containing resource and scopeSpans)
+    per line, following the same format as HttpExporter.
+    """
+
+    def __init__(self, file_path: str = "traces.jsonl", reset_on_start: bool = False) -> None:
+        """
+        Initialize the file exporter.
+        
+        Args:
+            file_path: Path to the file where traces will be written (default: "traces.jsonl")
+            reset_on_start: If True, the file will be cleared on first export. 
+                           If False, traces will be appended to the file.
+        """
+        self.file_path = file_path
+        self.reset_on_start = reset_on_start
+        self._lock = threading.Lock()
+        self._first_export = True
+
+    def export(self, spans: Iterable[Span]) -> bool:
+        """
+        Export spans to the file in JSONL format.
+        
+        Args:
+            spans: Iterable of Span objects to export
+            
+        Returns:
+            True if export succeeded, False otherwise
+        """
+        spans_list = list(spans)
+        if not spans_list:
+            return True
+
+        try:
+            payload = self._serialize(spans_list)
+            # Convert bytes to string for JSONL format
+            json_str = payload.decode("utf-8")
+            
+            with self._lock:
+                # Handle reset_on_start: clear file on first export if True
+                if self.reset_on_start and self._first_export:
+                    mode = "w"
+                    self._first_export = False
+                else:
+                    mode = "a"
+                    if self._first_export:
+                        self._first_export = False
+                
+                with open(self.file_path, mode, encoding="utf-8") as f:
+                    f.write(json_str)
+                    f.write("\n")  # JSONL format: one JSON object per line
+            
+            return True
+        except Exception:
+            # Silently fail on file write errors to avoid breaking the application
+            return False
+
+    def shutdown(self) -> None:
+        """Shutdown the exporter. No cleanup needed for file-based exporter."""
+        pass
+
+    def _serialize(self, spans: List[Span]) -> bytes:
+        """
+        Serialize spans to JSON bytes using the same format as HttpExporter.
+        
+        This method replicates the serialization logic from HttpExporter._serialize()
+        to ensure consistent format across exporters.
+        """
+        trunc = runtime_config.get_attr_truncation_limit()
+
+        def _truncate_str(s: str) -> str:
+            if trunc is None or trunc <= 0:
+                return s
+            if len(s) <= trunc:
+                return s
+            return s[: max(0, trunc - 1)] + "…"
+
+        def _sanitize(value: Any, depth: int = 0) -> Any:
+            # Keep payload JSON-safe and bounded.
+            if value is None or isinstance(value, (bool, int, float)):
+                return value
+            if isinstance(value, str):
+                return _truncate_str(value)
+            if depth >= 6:
+                return _truncate_str(repr(value))
+            if isinstance(value, dict):
+                out: Dict[str, Any] = {}
+                for k, v in value.items():
+                    try:
+                        key = str(k)
+                    except Exception:
+                        key = "<unstringifiable>"
+                    out[_truncate_str(key)] = _sanitize(v, depth + 1)
+                return out
+            if isinstance(value, (list, tuple, set)):
+                return [_sanitize(v, depth + 1) for v in list(value)[:100]]
+            # Fallback for unknown objects
+            return _truncate_str(repr(value))
+
+        def _status_code(status: SpanStatus) -> int:
+            # OTLP-style: 0=UNSET, 1=OK, 2=ERROR
+            if status == SpanStatus.OK:
+                return 1
+            if status == SpanStatus.ERROR:
+                return 2
+            return 0
+
+        def to_event(ev):
+            return {
+                "name": ev.get("name"),
+                "attributes": _sanitize(ev.get("attributes", {})),
+                "timestamp_ns": ev.get("timestamp_ns"),
+            }
+
+        resource_attrs: Dict[str, Any] = {}
+        try:
+            if spans and getattr(spans[0], "tracer", None) is not None:
+                provider = getattr(spans[0].tracer, "_provider", None)
+                if provider is not None:
+                    resource_attrs.update(getattr(provider, "resource", {}) or {})
+        except Exception:
+            resource_attrs = resource_attrs
+
+        # Add optional session/user identifiers to resource for easier querying.
+        if runtime_config.get_session_id():
+            resource_attrs.setdefault("session.id", runtime_config.get_session_id())
+        if runtime_config.get_user_id():
+            resource_attrs.setdefault("user.id", runtime_config.get_user_id())
+        if runtime_config.get_tenant_id():
+            resource_attrs.setdefault("tenant.id", runtime_config.get_tenant_id())
+        if runtime_config.get_project_id():
+            resource_attrs.setdefault("project.id", runtime_config.get_project_id())
+        if runtime_config.get_debug():
+            resource_attrs.setdefault("trace.debug", True)
+
+        payload = {
+            "resource": {"attributes": _sanitize(resource_attrs)},
+            "scopeSpans": [
+                {
+                    "scope": {"name": "agent-tracing-sdk", "version": "0.1.0"},
+                    "spans": [
+                        {
+                            "traceId": span.context.trace_id,
+                            "spanId": span.context.span_id,
+                            "parentSpanId": span.parent_span_id,
+                            "name": span.name,
+                            "startTimeUnixNano": span.start_time_ns,
+                            "endTimeUnixNano": span.end_time_ns,
+                            "attributes": _sanitize(span.attributes),
+                            "events": [to_event(e) for e in span.events],
+                            "status": {
+                                "code": _status_code(span.status),
+                                "message": span.status_description or "",
+                            },
+                        }
+                        for span in spans
+                    ],
+                }
+            ]
+        }
+        # Ensure we never raise due to serialization edge cases.
+        return json.dumps(payload, ensure_ascii=False).encode("utf-8")