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

traccia/exporter/http_exporter.py

@@ -0,0 +1,214 @@
+"""HTTP exporter with retry, backoff, and graceful shutdown."""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+from traccia.tracer.span import Span
+from traccia.tracer.span import SpanStatus
+from traccia import runtime_config
+
+TransientStatus = {429, 503, 504}
+DEFAULT_ENDPOINT = "https://api.dashboard.com/api/v1/traces"
+
+
+class HttpExporter:
+    """
+    Push spans to a backend over HTTP with retry/backoff.
+
+    A transport callable can be injected for testing. It should accept (payload_bytes, headers)
+    and return an HTTP status code integer.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = DEFAULT_ENDPOINT,
+        api_key: Optional[str] = None,
+        timeout: float = 10.0,
+        max_retries: int = 5,
+        backoff_base: float = 1.0,
+        backoff_jitter: float = 0.5,
+        transport: Optional[Callable[[bytes, dict], int]] = None,
+    ) -> None:
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base
+        self.backoff_jitter = backoff_jitter
+        self._transport = transport or self._http_post
+
+    def export(self, spans: Iterable[Span]) -> bool:
+        spans_list = list(spans)
+        if not spans_list:
+            return True
+
+        payload = self._serialize(spans_list)
+        headers = self._headers()
+
+        for attempt in range(self.max_retries):
+            status = self._safe_send(payload, headers)
+            if status is None:
+                status = 503  # treat transport errors as transient
+
+            if 200 <= status < 300:
+                return True
+
+            if status not in TransientStatus:
+                return False
+
+            sleep_for = self._compute_backoff(attempt)
+            time.sleep(sleep_for)
+
+        return False
+
+    def shutdown(self) -> None:
+        # No persistent connections when using urllib; if using requests Session it
+        # could be closed here. Kept for API symmetry.
+        pass
+
+    # Internal helpers
+    def _safe_send(self, payload: bytes, headers: dict) -> Optional[int]:
+        try:
+            return self._transport(payload, headers)
+        except Exception:
+            return None
+
+    def _compute_backoff(self, attempt: int) -> float:
+        base = self.backoff_base * (2 ** attempt)
+        jitter = random.uniform(0, self.backoff_jitter)
+        return base + jitter
+
+    def _headers(self) -> dict:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "agent-dashboard-sdk/0.1.0",
+            "X-SDK-Version": "0.1.0",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _serialize(self, spans: List[Span]) -> bytes:
+        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_agent_id():
+            resource_attrs.setdefault("agent.id", runtime_config.get_agent_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")
+
+    def _http_post(self, payload: bytes, headers: dict) -> int:
+        # Lightweight stdlib HTTP client to avoid extra deps.
+        # Run in empty context to prevent exporter's own HTTP calls from being instrumented
+        import urllib.request
+        from opentelemetry import context as context_api
+
+        # Run HTTP call in an empty context (no active span) to prevent instrumentation
+        # This ensures the exporter's HTTP calls don't create spans that pollute business traces
+        empty_context = context_api.Context()
+        token = context_api.attach(empty_context)
+        
+        try:
+            req = urllib.request.Request(
+                self.endpoint, data=payload, headers=headers, method="POST"
+            )
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.getcode()
+        except Exception:
+            return None
+        finally:
+            context_api.detach(token)
+

traccia/exporter/otlp_exporter.py

@@ -0,0 +1,190 @@
+"""OTLP exporter using OpenTelemetry OTLP HTTP exporter."""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Any
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter as OTelOTLPSpanExporter
+from opentelemetry.sdk.trace.export import SpanExporter as OTelSpanExporter, SpanExportResult
+
+
+class OTLPExporter:
+    """
+    OTLP exporter wrapper that maintains Traccia exporter interface.
+    
+    This wraps OpenTelemetry's OTLP HTTP exporter to work with Traccia's
+    BatchSpanProcessor which expects an `export()` method.
+    """
+
+    def __init__(
+        self,
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: float = 10.0,
+        headers: Optional[dict] = None,
+    ) -> None:
+        """
+        Initialize OTLP exporter.
+        
+        Args:
+            endpoint: OTLP endpoint URL (defaults to OTel default)
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds
+            headers: Optional additional headers
+        """
+        # Build headers
+        export_headers = dict(headers) if headers else {}
+        if api_key:
+            export_headers["Authorization"] = f"Bearer {api_key}"
+        
+        # Create OTel OTLP exporter
+        self._otel_exporter = OTelOTLPSpanExporter(
+            endpoint=endpoint,
+            timeout=timeout,
+            headers=export_headers if export_headers else None,
+        )
+        
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def export(self, spans: Iterable[Any]) -> bool:
+        """
+        Export spans using OTLP format.
+        
+        Args:
+            spans: Iterable of Traccia-compatible spans
+        
+        Returns:
+            True if export succeeded, False otherwise
+        """
+        spans_list = list(spans)
+        if not spans_list:
+            return True
+        
+        # Convert Traccia spans to OTel ReadableSpan format
+        from opentelemetry.sdk.trace.export import ReadableSpan
+        from opentelemetry.trace import SpanContext, TraceFlags, TraceState
+        from opentelemetry.sdk.trace import Resource
+        from opentelemetry.trace import Status, StatusCode
+        
+        from traccia.utils.helpers import parse_trace_id, parse_span_id
+        
+        readable_spans = []
+        
+        for span in spans_list:
+            # Get OTel span from Traccia wrapper
+            # Traccia Span wraps OTel Span
+            otel_span = None
+            
+            if hasattr(span, '_otel_span'):
+                otel_span = span._otel_span
+            elif isinstance(span, ReadableSpan):
+                # Already a ReadableSpan (from OTel SDK directly)
+                readable_spans.append(span)
+                continue
+            else:
+                # Try to use span directly if it's OTel-compatible
+                otel_span = span
+            
+            # Check if it's already a ReadableSpan (OTel SDK provides this when span ends)
+            if isinstance(otel_span, ReadableSpan):
+                readable_spans.append(otel_span)
+                continue
+            
+            # Try to get ReadableSpan from OTel span if it's ended
+            # OTel SDK stores ReadableSpan in the span's internal state when it ends
+            if hasattr(otel_span, '_readable_span'):
+                readable_spans.append(otel_span._readable_span)
+                continue
+            
+            # If OTel span is from SDK, try to get it from the span processor
+            # OTel SDK's BatchSpanProcessor receives ReadableSpan in on_end()
+            # But we're using our own processor, so we need to convert manually
+            
+            # Fallback: convert Traccia span to ReadableSpan manually
+            # This handles Traccia Span that wraps an active OTel Span
+            try:
+                # Parse trace/span IDs
+                trace_id = parse_trace_id(span.context.trace_id)
+                span_id = parse_span_id(span.context.span_id)
+                
+                # Create OTel SpanContext
+                trace_flags = TraceFlags(span.context.trace_flags)
+                trace_state = TraceState()
+                if span.context.trace_state:
+                    from traccia.context.propagators import parse_tracestate
+                    parsed = parse_tracestate(span.context.trace_state)
+                    if parsed:
+                        items = [(k, v) for k, v in parsed.items()]
+                        trace_state = TraceState(items)
+                
+                otel_context = SpanContext(
+                    trace_id=trace_id,
+                    span_id=span_id,
+                    is_remote=False,
+                    trace_flags=trace_flags,
+                    trace_state=trace_state,
+                )
+                
+                # Convert status
+                if span.status.value == 1:  # OK
+                    otel_status = Status(status_code=StatusCode.OK, description=span.status_description)
+                elif span.status.value == 2:  # ERROR
+                    otel_status = Status(status_code=StatusCode.ERROR, description=span.status_description)
+                else:
+                    otel_status = Status(status_code=StatusCode.UNSET, description=span.status_description)
+                
+                # Convert events
+                otel_events = []
+                if span.events:
+                    from opentelemetry.sdk.trace import Event
+                    for ev in span.events:
+                        otel_events.append(Event(
+                            name=ev.get("name", ""),
+                            timestamp=ev.get("timestamp_ns", span.start_time_ns),
+                            attributes=ev.get("attributes", {}),
+                        ))
+                
+                # Get resource
+                resource = Resource.create({})
+                if hasattr(span, 'tracer') and span.tracer:
+                    provider = getattr(span.tracer, '_provider', None)
+                    if provider:
+                        resource = provider._otel_provider.resource
+                
+                # Create ReadableSpan
+                readable_span = ReadableSpan(
+                    name=span.name,
+                    context=otel_context,
+                    parent=parse_span_id(span.parent_span_id) if span.parent_span_id else None,
+                    kind=None,  # Not available in Traccia
+                    start_time=span.start_time_ns,
+                    end_time=span.end_time_ns,
+                    status=otel_status,
+                    attributes=span.attributes,
+                    events=otel_events,
+                    links=[],
+                    resource=resource,
+                    instrumentation_scope=None,  # Will be set by OTel
+                )
+                readable_spans.append(readable_span)
+            except Exception:
+                # If conversion fails, skip this span
+                continue
+        
+        if not readable_spans:
+            return True
+        
+        # Export using OTel exporter
+        result = self._otel_exporter.export(readable_spans)
+        return result == SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """Shutdown the exporter."""
+        self._otel_exporter.shutdown()
+
+    def force_flush(self, timeout_millis: Optional[int] = None) -> None:
+        """Force flush any pending spans."""
+        timeout = timeout_millis / 1000.0 if timeout_millis else None
+        self._otel_exporter.force_flush(timeout_millis=int(timeout * 1000) if timeout else 30000)

traccia/instrumentation/__init__.py

@@ -0,0 +1,26 @@
+"""Infrastructure and vendor instrumentation.
+
+This module exposes helpers for HTTP client/server tracing (including FastAPI),
+vendor SDK patching (OpenAI, Anthropic, requests), and decorators used for
+auto-instrumentation.
+"""
+
+from traccia.instrumentation.decorator import observe
+from traccia.instrumentation.openai import patch_openai, patch_openai_responses
+from traccia.instrumentation.anthropic import patch_anthropic
+from traccia.instrumentation.requests import patch_requests
+from traccia.instrumentation.http_client import inject_headers as inject_http_headers
+from traccia.instrumentation.http_server import extract_parent_context, start_server_span
+from traccia.instrumentation.fastapi import install_http_middleware
+
+__all__ = [
+    "observe",
+    "patch_openai",
+    "patch_openai_responses",
+    "patch_anthropic",
+    "patch_requests",
+    "inject_http_headers",
+    "extract_parent_context",
+    "start_server_span",
+    "install_http_middleware",
+]

traccia/instrumentation/anthropic.py

@@ -0,0 +1,92 @@
+"""Anthropic monkey patching for messages.create."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from traccia.tracer.span import SpanStatus
+
+_patched = False
+
+
+def _safe_get(obj, path: str, default=None):
+    cur = obj
+    for part in path.split("."):
+        if cur is None:
+            return default
+        if isinstance(cur, dict):
+            cur = cur.get(part)
+        else:
+            cur = getattr(cur, part, None)
+    return cur if cur is not None else default
+
+
+def patch_anthropic() -> bool:
+    """Patch Anthropic messages.create; returns True if patched, False otherwise."""
+    global _patched
+    if _patched:
+        return True
+    try:
+        import anthropic
+    except Exception:
+        return False
+
+    client_cls = getattr(anthropic, "Anthropic", None)
+    if client_cls is None:
+        return False
+
+    original = getattr(client_cls, "messages", None)
+    if original is None:
+        return False
+
+    create_fn = getattr(original, "create", None)
+    if create_fn is None:
+        return False
+    if getattr(create_fn, "_agent_trace_patched", False):
+        _patched = True
+        return True
+
+    def wrapped_create(self, *args, **kwargs):
+        tracer = _get_tracer("anthropic")
+        model = kwargs.get("model") or _safe_get(args, "0.model", None)
+        attributes: Dict[str, Any] = {"llm.vendor": "anthropic"}
+        if model:
+            attributes["llm.model"] = model
+        with tracer.start_as_current_span("llm.anthropic.messages", attributes=attributes) as span:
+            try:
+                resp = create_fn(self, *args, **kwargs)
+                usage = getattr(resp, "usage", None) or resp.get("usage") if isinstance(resp, dict) else None
+                if usage:
+                    span.set_attribute("llm.usage.source", "provider_usage")
+                    for k in ("input_tokens", "output_tokens"):
+                        if k in usage:
+                            span.set_attribute(f"llm.usage.{k}", usage[k])
+                    # Provide OpenAI-style aliases so downstream processors (cost, etc.)
+                    # can treat Anthropic uniformly.
+                    if "input_tokens" in usage and "llm.usage.prompt_tokens" not in span.attributes:
+                        span.set_attribute("llm.usage.prompt_tokens", usage["input_tokens"])
+                    if "input_tokens" in usage:
+                        span.set_attribute("llm.usage.prompt_source", "provider_usage")
+                    if "output_tokens" in usage and "llm.usage.completion_tokens" not in span.attributes:
+                        span.set_attribute("llm.usage.completion_tokens", usage["output_tokens"])
+                    if "output_tokens" in usage:
+                        span.set_attribute("llm.usage.completion_source", "provider_usage")
+                stop_reason = _safe_get(resp, "stop_reason") or _safe_get(resp, "stop_reason", None)
+                if stop_reason:
+                    span.set_attribute("llm.stop_reason", stop_reason)
+                return resp
+            except Exception as exc:
+                span.record_exception(exc)
+                span.set_status(SpanStatus.ERROR, str(exc))
+                raise
+
+    wrapped_create._agent_trace_patched = True
+    setattr(original, "create", wrapped_create)
+    _patched = True
+    return True
+
+
+def _get_tracer(name: str):
+    import traccia
+
+    return traccia.get_tracer(name)
+