spanwire 0.1.0__py3-none-any.whl

spanwire/sampler.py

@@ -0,0 +1,108 @@
+"""Trace sampling algorithms for spanwire."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from spanwire.core import SpanContext
+
+
+class Sampler(ABC):
+    """Abstract base class for all spanwire samplers."""
+
+    @abstractmethod
+    def should_sample(
+        self,
+        parent_context: Optional[SpanContext],
+        trace_id: str,
+        name: str,
+    ) -> bool:
+        """Determine if a trace should be sampled."""
+        pass
+
+
+class AlwaysOnSampler(Sampler):
+    """Samples every trace."""
+
+    def should_sample(
+        self,
+        parent_context: Optional[SpanContext],
+        trace_id: str,
+        name: str,
+    ) -> bool:
+        return True
+
+    def __repr__(self) -> str:
+        return "AlwaysOnSampler()"
+
+
+class AlwaysOffSampler(Sampler):
+    """Drops every trace."""
+
+    def should_sample(
+        self,
+        parent_context: Optional[SpanContext],
+        trace_id: str,
+        name: str,
+    ) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "AlwaysOffSampler()"
+
+
+class RatioSampler(Sampler):
+    """Deterministic ratio-based trace sampler using trace_id hashing.
+
+    Guarantees consistent sampling decisions for the same trace across services.
+    """
+
+    def __init__(self, ratio: float) -> None:
+        if not (0.0 <= ratio <= 1.0):
+            raise ValueError(f"Ratio must be between 0.0 and 1.0, got {ratio}")
+        self.ratio = float(ratio)
+        # 32-bit unsigned threshold
+        self._threshold = int(self.ratio * 0xFFFFFFFF)
+
+    def should_sample(
+        self,
+        parent_context: Optional[SpanContext],
+        trace_id: str,
+        name: str,
+    ) -> bool:
+        if self.ratio <= 0.0:
+            return False
+        if self.ratio >= 1.0:
+            return True
+        # Extract lower 8 hex characters (32 bits) of the trace_id
+        tail = trace_id[-8:] if len(trace_id) >= 8 else trace_id
+        try:
+            val = int(tail, 16)
+            return val <= self._threshold
+        except ValueError:
+            return False
+
+    def __repr__(self) -> str:
+        return f"RatioSampler(ratio={self.ratio})"
+
+
+class ParentBasedSampler(Sampler):
+    """Honors parent context sampling decision if present; otherwise delegates to root sampler."""
+
+    def __init__(self, root: Optional[Sampler] = None) -> None:
+        self.root: Sampler = root if root is not None else AlwaysOnSampler()
+
+    def should_sample(
+        self,
+        parent_context: Optional[SpanContext],
+        trace_id: str,
+        name: str,
+    ) -> bool:
+        if parent_context is not None:
+            return parent_context.is_sampled
+        return self.root.should_sample(parent_context, trace_id, name)
+
+    def __repr__(self) -> str:
+        return f"ParentBasedSampler(root={self.root!r})"

spanwire/w3c.py

@@ -0,0 +1,160 @@
+"""W3C Trace Context and Baggage standard implementation.
+
+Compliant with:
+- W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/)
+- W3C Baggage Recommendation (https://www.w3.org/TR/baggage/)
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from typing import Dict, Mapping, Optional, Tuple
+
+TRACEPARENT_REGEX = re.compile(
+    r"^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(?:-.*)?$"
+)
+INVALID_TRACE_ID = "0" * 32
+INVALID_SPAN_ID = "0" * 16
+
+
+def is_valid_trace_id(trace_id: str) -> bool:
+    """Check if trace_id is a valid 32-character hex string and not all zeros."""
+    if not isinstance(trace_id, str) or len(trace_id) != 32:
+        return False
+    if trace_id == INVALID_TRACE_ID:
+        return False
+    return bool(re.fullmatch(r"[0-9a-f]{32}", trace_id))
+
+
+def is_valid_span_id(span_id: str) -> bool:
+    """Check if span_id is a valid 16-character hex string and not all zeros."""
+    if not isinstance(span_id, str) or len(span_id) != 16:
+        return False
+    if span_id == INVALID_SPAN_ID:
+        return False
+    return bool(re.fullmatch(r"[0-9a-f]{16}", span_id))
+
+
+def format_traceparent(
+    trace_id: str,
+    span_id: str,
+    trace_flags: int = 1,
+    version: str = "00",
+) -> str:
+    """Format trace context into a W3C traceparent header string."""
+    flags_hex = f"{trace_flags & 0xFF:02x}"
+    return f"{version}-{trace_id.lower()}-{span_id.lower()}-{flags_hex}"
+
+
+def parse_traceparent(header_value: str) -> Optional[Tuple[str, str, int]]:
+    """Parse a W3C traceparent header.
+
+    Returns:
+        (trace_id, parent_span_id, trace_flags) or None if malformed/invalid.
+    """
+    if not header_value or not isinstance(header_value, str):
+        return None
+
+    clean_value = header_value.strip().lower()
+    match = TRACEPARENT_REGEX.match(clean_value)
+    if not match:
+        return None
+
+    version, trace_id, parent_id, flags_hex = match.groups()
+
+    # Version 'ff' is explicitly invalid according to W3C spec
+    if version == "ff":
+        return None
+
+    # Version 00 cannot have trailing fields
+    if version == "00" and len(clean_value) != 55:
+        return None
+
+    # All zeros are forbidden for trace_id and parent_id
+    if trace_id == INVALID_TRACE_ID or parent_id == INVALID_SPAN_ID:
+        return None
+
+    try:
+        flags = int(flags_hex, 16)
+    except ValueError:
+        return None
+
+    return trace_id, parent_id, flags
+
+
+def format_baggage(baggage: Mapping[str, str]) -> str:
+    """Format key-value pairs into a W3C baggage header."""
+    if not baggage:
+        return ""
+    entries = []
+    for k, v in baggage.items():
+        k_enc = urllib.parse.quote(str(k).strip(), safe="")
+        v_enc = urllib.parse.quote(str(v).strip(), safe="")
+        if k_enc:
+            entries.append(f"{k_enc}={v_enc}")
+    return ", ".join(entries)
+
+
+def parse_baggage(header_value: str) -> Dict[str, str]:
+    """Parse a W3C baggage header into a dictionary of key-value pairs."""
+    baggage: Dict[str, str] = {}
+    if not header_value or not isinstance(header_value, str):
+        return baggage
+
+    for member in header_value.split(","):
+        member = member.strip()
+        if not member:
+            continue
+        # Split on semicolon first to ignore properties (e.g. key=val;prop=x)
+        parts = member.split(";", 1)
+        key_val = parts[0].strip()
+        if "=" in key_val:
+            k, v = key_val.split("=", 1)
+            k = urllib.parse.unquote(k.strip())
+            v = urllib.parse.unquote(v.strip())
+            if k:
+                baggage[k] = v
+    return baggage
+
+
+def extract_w3c_headers(
+    headers: Mapping[str, str],
+) -> Tuple[Optional[Tuple[str, str, int]], Dict[str, str], str]:
+    """Extract traceparent, baggage, and tracestate from HTTP headers.
+
+    Headers lookup is case-insensitive.
+    Returns:
+        (traceparent_tuple_or_none, baggage_dict, tracestate_str)
+    """
+    normalized = {k.lower(): v for k, v in headers.items()}
+
+    traceparent_val = normalized.get("traceparent")
+    parsed_tp = parse_traceparent(traceparent_val) if traceparent_val else None
+
+    baggage_val = normalized.get("baggage", "")
+    parsed_baggage = parse_baggage(baggage_val)
+
+    tracestate = normalized.get("tracestate", "").strip()
+
+    return parsed_tp, parsed_baggage, tracestate
+
+
+def inject_w3c_headers(
+    trace_id: str,
+    span_id: str,
+    trace_flags: int = 1,
+    baggage: Optional[Mapping[str, str]] = None,
+    tracestate: str = "",
+    target_headers: Optional[Dict[str, str]] = None,
+) -> Dict[str, str]:
+    """Inject W3C traceparent, baggage, and tracestate into a header dictionary."""
+    out = target_headers if target_headers is not None else {}
+    out["traceparent"] = format_traceparent(trace_id, span_id, trace_flags)
+    if baggage:
+        formatted_baggage = format_baggage(baggage)
+        if formatted_baggage:
+            out["baggage"] = formatted_baggage
+    if tracestate:
+        out["tracestate"] = tracestate
+    return out

spanwire-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: spanwire
+Version: 0.1.0
+Summary: Zero-dependency micro-tracing, distributed context propagation & breadcrumb telemetry engine for Python.
+Author-email: Hamidreza <h4midrezam@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mrhamidrezam/spanwire
+Project-URL: Repository, https://github.com/mrhamidrezam/spanwire
+Project-URL: Issues, https://github.com/mrhamidrezam/spanwire/issues
+Keywords: tracing,distributed-tracing,opentelemetry,w3c,traceparent,baggage,breadcrumbs,telemetry,contextvars,zero-dependency,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# ⚡ spanwire
+
+**Zero-dependency micro-tracing, distributed context propagation & breadcrumb telemetry engine for Python.**
+
+[![PyPI Version](https://img.shields.io/pypi/v/spanwire.svg?color=blue)](https://pypi.org/project/spanwire/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/spanwire.svg)](https://pypi.org/project/spanwire/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/mrhamidrezam/spanwire/actions/workflows/ci.yml/badge.svg)](https://github.com/mrhamidrezam/spanwire/actions/workflows/ci.yml)
+[![Typing: Typed](https://img.shields.io/badge/typing-typed-purple.svg)](https://peps.python.org/pep-0561/)
+[![Dependencies: Zero](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#)
+
+</div>
+
+---
+
+## 💡 Why spanwire?
+
+Standard distributed tracing solutions (like OpenTelemetry SDK) pull in dozens of heavy transitive dependencies, incur noticeable startup delays, and add architectural bloat to lightweight microservices, CLI utilities, serverless functions (AWS Lambda, Cloud Run), and async LLM pipelines.
+
+**spanwire** delivers enterprise-grade distributed telemetry and error context trails with **zero external dependencies**, utilizing pure Python standard library primitives (`contextvars`, `dataclasses`, `time`, `secrets`).
+
+- **100% W3C Trace Context & Baggage Standard**: Interoperable with Datadog, Jaeger, Grafana Tempo, AWS X-Ray, and OpenTelemetry collectors.
+- **Flawless Context Propagation**: Works out of the box across `asyncio` coroutines, background tasks, and OS threads without context leakage.
+- **In-Memory Breadcrumb Trail**: Maintains an efficient circular ring-buffer of recent operational milestones, automatically attached when errors or exceptions occur.
+- **Multiple Exporters**: ANSI-colorized CLI console, NDJSON/JSONLines for log aggregators (Vector, Fluentd, Promtail), or in-memory collectors for unit testing.
+- **Deterministic Sampling**: Ratio-based trace hashing guarantees synchronized sampling decisions across distributed microservice boundaries.
+
+---
+
+## 📐 Architecture & Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as API Gateway (Service A)
+    participant Wire as W3C HTTP Headers
+    participant Worker as Downstream Worker (Service B)
+    participant Exporter as Telemetry Exporter
+
+    Client->>Client: Start Span ("checkout.process")
+    Client->>Client: Record Breadcrumb ("User tier: VIP")
+    Client->>Wire: Inject W3C traceparent & baggage headers
+    Wire->>Worker: Forward HTTP Request
+    Worker->>Worker: Extract W3C Context (inherits trace_id)
+    Worker->>Worker: Execute child span ("db.persist_order")
+    Worker-->>Exporter: Export child span ([OK] 12.4ms)
+    Client-->>Exporter: Export parent span ([OK] 45.1ms)
+```
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install spanwire
+```
+
+*Requires Python 3.10 or higher. No third-party dependencies required.*
+
+---
+
+## ⚡ Quick Start
+
+### 1. Basic Spans and Console Export
+
+```python
+import time
+from spanwire import Tracer, ConsoleExporter
+
+tracer = Tracer(
+    service_name="payment-service",
+    exporter=ConsoleExporter(colored=True)
+)
+
+tracer.add_breadcrumb("Validating customer cart", category="cart")
+
+with tracer.span("process_payment", attributes={"order.id": "ord_1042", "amount": 89.00}) as span:
+    time.sleep(0.02)
+    
+    # Nested child span
+    with tracer.span("stripe.charge") as child:
+        time.sleep(0.03)
+        child.set_attribute("charge.id", "ch_abc123")
+        tracer.add_breadcrumb("Payment captured via webhook", category="billing")
+```
+
+Console Output:
+```text
+⚡ [OK] stripe.charge (30.12ms) [trace=63d3791c.. span=ff0dba3fa8e11f3c parent=97bc44600e80142d]
+   ↳ attributes: service.name='payment-service', charge.id='ch_abc123'
+   ↳ breadcrumbs (2):
+     - [INFO] cart: Validating customer cart
+     - [INFO] billing: Payment captured via webhook
+⚡ [OK] process_payment (50.84ms) [trace=63d3791c.. span=97bc44600e80142d]
+   ↳ attributes: service.name='payment-service', order.id='ord_1042', amount=89.0
+```
+
+---
+
+### 2. Distributed Tracing over HTTP (W3C Traceparent & Baggage)
+
+```python
+import requests
+from spanwire import Tracer, set_baggage_item
+
+tracer = Tracer(service_name="gateway")
+
+# Set user context in baggage
+set_baggage_item("user_id", "u_8841")
+
+with tracer.span("http_outgoing_call") as span:
+    # 1. Inject W3C headers into outbound HTTP request
+    headers = {}
+    tracer.inject_headers(headers)
+    # headers contains:
+    # 'traceparent': '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
+    # 'baggage': 'user_id=u_8841'
+
+    # requests.get("https://worker.internal/api/tasks", headers=headers)
+```
+
+On the receiving downstream service:
+
+```python
+from spanwire import Tracer
+
+worker_tracer = Tracer(service_name="worker")
+
+def handle_incoming_request(incoming_headers: dict):
+    # Extract parent context & baggage from headers
+    parent_ctx, baggage, _ = worker_tracer.extract_headers(incoming_headers)
+
+    # Continue the distributed trace seamlessly
+    with worker_tracer.span("worker.handle_job", parent_context=parent_ctx) as span:
+        print(f"Propagated trace_id: {span.context.trace_id}")
+        print(f"Parent span_id:      {span.parent_span_id}")
+        print(f"User ID from baggage: {baggage.get('user_id')}")
+```
+
+---
+
+### 3. Asynchronous Function Decoration & LLM Agent Pipeline
+
+```python
+import asyncio
+from spanwire import Tracer, ConsoleExporter
+
+tracer = Tracer(service_name="llm-orchestrator", exporter=ConsoleExporter())
+
+@tracer.trace(name="llm.generate_plan")
+async def generate_plan(prompt: str) -> list[str]:
+    tracer.add_breadcrumb(f"Generating plan for: {prompt[:30]}", category="llm")
+    await asyncio.sleep(0.05)
+    return ["search_db", "render_markdown"]
+
+async def main():
+    with tracer.span("orchestrate_query"):
+        plan = await generate_plan("Summarize latest server telemetry")
+
+asyncio.run(main())
+```
+
+---
+
+## 🛠️ Exporters
+
+| Exporter | Description | Best Suited For |
+|---|---|---|
+| `ConsoleExporter` | Formatted CLI output with ANSI colors, durations, and breadcrumb trails | Development, debugging, CLI tools |
+| `JsonLinesExporter` | Newline-delimited JSON (NDJSON) output to file or stdout | Vector, Promtail, Datadog Agent, CloudWatch |
+| `InMemoryExporter` | Stores finished spans in a thread-safe list | Pytest unit assertions, custom telemetry queues |
+| `CallbackExporter` | Invokes custom callback function on each completed span | Custom event emission, Webhooks |
+
+---
+
+## 🎯 Samplers
+
+- **`AlwaysOnSampler()`**: Traces 100% of operations (default).
+- **`AlwaysOffSampler()`**: Disables tracing overhead completely.
+- **`RatioSampler(ratio=0.1)`**: Probabilistically samples `10%` of traces using deterministic hashing on `trace_id`.
+- **`ParentBasedSampler(root=...)`**: Respects the upstream service's sampling flag, with fallback to root sampler.
+
+---
+
+## 🧪 Running Unit Tests
+
+```bash
+python -m pytest tests -v
+```
+
+All 33 unit tests execute in ~0.15s with zero external test plugins.
+
+---
+
+## 📜 License
+
+MIT License © 2026 Hamidreza Moghaddam Kohi. See [LICENSE](LICENSE) for details.

spanwire-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+spanwire/__init__.py,sha256=t75NacFTB50nG-8oR1SFS_Vquy0AK_PK5qmQQpSXdVU,3395
+spanwire/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+spanwire/breadcrumbs.py,sha256=2ZtSNTmfcFOfHv2BR5GbeMEC8iFjP-qYse9hSAJiEck,2653
+spanwire/context.py,sha256=98CZk0_ObKjOc2mHJXkheKqJZB-IOzIALRYP3vwoBOE,1927
+spanwire/core.py,sha256=uyIkeGQNDHG4-D9maR9THtYGii1LSvB-q_O3aVHQgmI,14085
+spanwire/exporters.py,sha256=HwTOdyxkkV1Nu70h7iHtrOJycrXLTamstsIIjogmOhE,6211
+spanwire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spanwire/sampler.py,sha256=Lbujg_7Q6U1hUme0P5a7WTVR-3hPCsYh-WdEHyZfieQ,2871
+spanwire/w3c.py,sha256=ZU8_2XmtAIuzmTDEm-aDMOp8Mi_EzWwfZEKpSD9GhAY,5022
+spanwire-0.1.0.dist-info/licenses/LICENSE,sha256=SzrgpH9v6YiNHAbiye6l8jqMihAM3_tt_nJkrHS2A6Q,1081
+spanwire-0.1.0.dist-info/METADATA,sha256=izqOqQZWOK4Tv6-3xxOTy5BaO5PwnbAHf5Nf9bVFnNM,8479
+spanwire-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+spanwire-0.1.0.dist-info/top_level.txt,sha256=1_NlRrHckhHPZjLE-DZnMe3DEjty4MzNzKJk_xe-U5g,9
+spanwire-0.1.0.dist-info/RECORD,,

spanwire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spanwire-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamidreza Moghaddam Kohi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spanwire-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spanwire