spanwire 0.1.0__py3-none-any.whl

spanwire/__init__.py

@@ -0,0 +1,145 @@
+"""spanwire: Zero-dependency micro-tracing, distributed context propagation & breadcrumb telemetry engine for Python."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from spanwire._version import __version__
+from spanwire.breadcrumbs import Breadcrumb, BreadcrumbBuffer
+from spanwire.context import (
+    clear_baggage,
+    get_baggage,
+    get_baggage_item,
+    get_current_span,
+    set_baggage,
+    set_baggage_item,
+)
+from spanwire.core import (
+    Span,
+    SpanContext,
+    SpanEvent,
+    SpanStatus,
+    Tracer,
+    generate_span_id,
+    generate_trace_id,
+)
+from spanwire.exporters import (
+    CallbackExporter,
+    ConsoleExporter,
+    InMemoryExporter,
+    JsonLinesExporter,
+    SpanExporter,
+)
+from spanwire.sampler import (
+    AlwaysOffSampler,
+    AlwaysOnSampler,
+    ParentBasedSampler,
+    RatioSampler,
+    Sampler,
+)
+from spanwire.w3c import (
+    extract_w3c_headers,
+    format_baggage,
+    format_traceparent,
+    inject_w3c_headers,
+    is_valid_span_id,
+    is_valid_trace_id,
+    parse_baggage,
+    parse_traceparent,
+)
+
+_DEFAULT_TRACER: Optional[Tracer] = None
+
+
+def get_tracer(service_name: str = "default-service") -> Tracer:
+    """Get or initialize the global default Tracer."""
+    global _DEFAULT_TRACER
+    if _DEFAULT_TRACER is None:
+        _DEFAULT_TRACER = Tracer(service_name=service_name)
+    return _DEFAULT_TRACER
+
+
+def set_tracer(tracer: Tracer) -> None:
+    """Set the global default Tracer."""
+    global _DEFAULT_TRACER
+    _DEFAULT_TRACER = tracer
+
+
+def span(
+    name: str,
+    attributes: Optional[Mapping[str, Any]] = None,
+    parent_context: Optional[SpanContext] = None,
+) -> Span:
+    """Create a span on the default global tracer."""
+    return get_tracer().span(name, attributes=attributes, parent_context=parent_context)
+
+
+def trace(
+    name: Optional[str] = None,
+    attributes: Optional[Mapping[str, Any]] = None,
+) -> Callable[..., Any]:
+    """Decorator to trace a function using the default global tracer."""
+    return get_tracer().trace(name=name, attributes=attributes)
+
+
+def add_breadcrumb(
+    message: str,
+    level: str = "INFO",
+    category: str = "default",
+    data: Optional[Dict[str, Any]] = None,
+    **kwargs: Any,
+) -> Breadcrumb:
+    """Add a breadcrumb to the default global tracer."""
+    return get_tracer().add_breadcrumb(
+        message=message, level=level, category=category, data=data, **kwargs
+    )
+
+
+__all__ = [
+    "__version__",
+    # Core
+    "Tracer",
+    "Span",
+    "SpanContext",
+    "SpanEvent",
+    "SpanStatus",
+    "generate_trace_id",
+    "generate_span_id",
+    # Global conveniences
+    "get_tracer",
+    "set_tracer",
+    "span",
+    "trace",
+    "add_breadcrumb",
+    # Context
+    "get_current_span",
+    "get_baggage",
+    "set_baggage",
+    "set_baggage_item",
+    "get_baggage_item",
+    "clear_baggage",
+    # Breadcrumbs
+    "Breadcrumb",
+    "BreadcrumbBuffer",
+    # Samplers
+    "Sampler",
+    "AlwaysOnSampler",
+    "AlwaysOffSampler",
+    "RatioSampler",
+    "ParentBasedSampler",
+    # Exporters
+    "SpanExporter",
+    "InMemoryExporter",
+    "JsonLinesExporter",
+    "ConsoleExporter",
+    "CallbackExporter",
+    # W3C
+    "format_traceparent",
+    "parse_traceparent",
+    "format_baggage",
+    "parse_baggage",
+    "inject_w3c_headers",
+    "extract_w3c_headers",
+    "is_valid_trace_id",
+    "is_valid_span_id",
+]

spanwire/_version.py

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

spanwire/breadcrumbs.py

@@ -0,0 +1,88 @@
+"""Breadcrumb trail telemetry buffer for debugging contextual application state."""
+
+from __future__ import annotations
+
+import collections
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Breadcrumb:
+    """An individual recorded breadcrumb milestone in the telemetry trail."""
+
+    message: str
+    level: str = "INFO"
+    category: str = "default"
+    timestamp: float = field(default_factory=time.time)
+    data: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert breadcrumb to dictionary representation."""
+        return {
+            "message": self.message,
+            "level": self.level.upper(),
+            "category": self.category,
+            "timestamp": self.timestamp,
+            "data": dict(self.data),
+        }
+
+
+class BreadcrumbBuffer:
+    """Thread-safe bounded ring buffer holding recent breadcrumbs."""
+
+    def __init__(self, capacity: int = 50) -> None:
+        if capacity <= 0:
+            raise ValueError(f"Capacity must be positive, got {capacity}")
+        self.capacity = capacity
+        self._deque: collections.deque[Breadcrumb] = collections.deque(maxlen=capacity)
+        self._lock = threading.Lock()
+
+    def add(self, crumb: Breadcrumb) -> None:
+        """Add an existing breadcrumb into the buffer."""
+        with self._lock:
+            self._deque.append(crumb)
+
+    def record(
+        self,
+        message: str,
+        level: str = "INFO",
+        category: str = "default",
+        data: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Breadcrumb:
+        """Create and record a breadcrumb in one step."""
+        merged_data: Dict[str, Any] = {}
+        if data:
+            merged_data.update(data)
+        if kwargs:
+            merged_data.update(kwargs)
+
+        crumb = Breadcrumb(
+            message=message,
+            level=level.upper(),
+            category=category,
+            timestamp=time.time(),
+            data=merged_data,
+        )
+        self.add(crumb)
+        return crumb
+
+    def get_crumbs(self) -> List[Breadcrumb]:
+        """Return a snapshot copy of current breadcrumbs in chronological order."""
+        with self._lock:
+            return list(self._deque)
+
+    def clear(self) -> None:
+        """Clear all stored breadcrumbs."""
+        with self._lock:
+            self._deque.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._deque)
+
+    def __repr__(self) -> str:
+        return f"BreadcrumbBuffer(count={len(self)}, capacity={self.capacity})"

spanwire/context.py

@@ -0,0 +1,59 @@
+"""Context storage and propagation using Python contextvars for sync and async code."""
+
+from __future__ import annotations
+
+import contextvars
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+if TYPE_CHECKING:
+    from spanwire.core import Span
+
+_CURRENT_SPAN: contextvars.ContextVar[Optional[Span]] = contextvars.ContextVar(
+    "spanwire_current_span", default=None
+)
+
+_CURRENT_BAGGAGE: contextvars.ContextVar[Dict[str, str]] = contextvars.ContextVar(
+    "spanwire_current_baggage", default={}
+)
+
+
+def get_current_span() -> Optional[Span]:
+    """Retrieve the currently active Span in the current execution context."""
+    return _CURRENT_SPAN.get()
+
+
+def set_current_span(span: Optional[Span]) -> contextvars.Token[Optional[Span]]:
+    """Set the active Span and return the restoration token."""
+    return _CURRENT_SPAN.set(span)
+
+
+def reset_current_span(token: contextvars.Token[Optional[Span]]) -> None:
+    """Reset the active Span to its state prior to set_current_span."""
+    _CURRENT_SPAN.reset(token)
+
+
+def get_baggage() -> Dict[str, str]:
+    """Get a copy of the current context's baggage key-values."""
+    return dict(_CURRENT_BAGGAGE.get())
+
+
+def set_baggage(baggage: Dict[str, str]) -> contextvars.Token[Dict[str, str]]:
+    """Set the entire baggage dictionary in context."""
+    return _CURRENT_BAGGAGE.set(dict(baggage))
+
+
+def set_baggage_item(key: str, value: str) -> None:
+    """Set or update an individual baggage item in the current context."""
+    current = dict(_CURRENT_BAGGAGE.get())
+    current[str(key).strip()] = str(value).strip()
+    _CURRENT_BAGGAGE.set(current)
+
+
+def get_baggage_item(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get an individual baggage item value from context."""
+    return _CURRENT_BAGGAGE.get().get(str(key).strip(), default)
+
+
+def clear_baggage() -> None:
+    """Clear all baggage in the current context."""
+    _CURRENT_BAGGAGE.set({})