blitz-sdk 0.1.0__py3-none-any.whl

blitz/__init__.py

@@ -0,0 +1,121 @@
+"""blitz — drop-in distributed tracing for LLM calls.
+
+Usage:
+
+    import blitz
+
+    blitz.init(
+        project_id="proj_abc",
+        api_key="sk_...",
+        endpoint="https://api.sparepartslabs.com",
+        sample_rate=0.1,
+    )
+
+After init(), any OpenAI / Anthropic / Gemini call made in this process is traced
+and shipped to the blitz backend. Nothing else in your code changes.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+from typing import Callable, Optional
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+
+from ._exporter import BlitzSpanExporter
+from ._instrument import instrument_providers
+
+__all__ = ["init"]
+
+logger = logging.getLogger("blitz")
+
+_initialized = False
+
+
+def init(
+    *,
+    project_id: str,
+    api_key: str,
+    endpoint: str,
+    sample_rate: float = 1.0,
+    capture_content: bool = True,
+    redact: Optional[Callable[[str], str]] = None,
+    max_content_chars: int = 24_000,
+    service_name: str = "llm-app",
+) -> list[str]:
+    """Initialize blitz tracing.
+
+    Args:
+        project_id: Your blitz project id (multitenancy key).
+        api_key: Project API key, sent as the ``x-api-key`` header.
+        endpoint: Base URL of the blitz backend, e.g.
+            ``https://api.sparepartslabs.com``. The SDK posts to
+            ``{endpoint}/blitz/v1/traces``.
+        sample_rate: Head sampling ratio in [0.0, 1.0]. 0.1 = trace 10% of
+            requests. Sampling is parent-based so a sampled trace keeps all its
+            child spans.
+        capture_content: When False, prompts/completions are stripped before
+            export — only metadata (model, tokens, latency, cost) is sent.
+        redact: Optional callable applied to every prompt/completion string
+            before export (PII scrubbing).
+        max_content_chars: Hard cap per content field; longer values are
+            truncated with a ``…[truncated]`` marker.
+        service_name: Logical service name attached to every span.
+
+    Returns:
+        The list of providers that were successfully instrumented
+        (e.g. ``["openai", "anthropic"]``).
+    """
+    global _initialized
+    if _initialized:
+        logger.warning("blitz.init() called more than once; ignoring")
+        return []
+
+    if not 0.0 <= sample_rate <= 1.0:
+        raise ValueError("sample_rate must be between 0.0 and 1.0")
+
+    # Tell the underlying instrumentors not to capture prompt content at the
+    # source when the caller opted out — cheaper and avoids the content ever
+    # entering a span. The exporter enforces this again as a backstop.
+    if not capture_content:
+        os.environ.setdefault("TRACELOOP_TRACE_CONTENT", "false")
+
+    resource = Resource.create(
+        {
+            "service.name": service_name,
+            "blitz.project_id": project_id,
+        }
+    )
+    provider = TracerProvider(
+        resource=resource,
+        sampler=ParentBased(TraceIdRatioBased(sample_rate)),
+    )
+
+    exporter = BlitzSpanExporter(
+        endpoint=endpoint,
+        api_key=api_key,
+        project_id=project_id,
+        capture_content=capture_content,
+        redact=redact,
+        max_content_chars=max_content_chars,
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+    instrumented = instrument_providers(provider)
+    atexit.register(provider.shutdown)
+
+    _initialized = True
+    logger.info(
+        "blitz initialized — project=%s providers=[%s] sample_rate=%s",
+        project_id,
+        ", ".join(instrumented) or "none",
+        sample_rate,
+    )
+    return instrumented

blitz/_exporter.py

@@ -0,0 +1,182 @@
+"""Span exporter that converts OTel GenAI spans into blitz's wire format and
+POSTs them to the blitz backend.
+
+We use our own JSON shape (not raw OTLP) because we own both ends — it keeps the
+FastAPI ingest endpoint trivial and lets redaction happen cleanly during the
+conversion step rather than mutating immutable OTel spans. The instrumentors
+still emit standard OTel spans, so a customer can additionally attach a vanilla
+OTLP exporter to fan telemetry out to Datadog/Phoenix/etc.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from typing import Callable, Optional, Sequence
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.trace import StatusCode
+
+logger = logging.getLogger("blitz")
+
+_PROMPT_PREFIX = "gen_ai.prompt."
+_COMPLETION_PREFIX = "gen_ai.completion."
+
+
+class BlitzSpanExporter(SpanExporter):
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        api_key: str,
+        project_id: str,
+        capture_content: bool = True,
+        redact: Optional[Callable[[str], str]] = None,
+        max_content_chars: int = 24_000,
+        timeout: float = 10.0,
+    ) -> None:
+        self._url = endpoint.rstrip("/") + "/blitz/v1/traces"
+        self._headers = {"content-type": "application/json", "x-api-key": api_key}
+        self._project_id = project_id
+        self._capture_content = capture_content
+        self._redact = redact
+        self._max = max_content_chars
+        self._timeout = timeout
+
+    # -- SpanExporter interface ---------------------------------------------
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        try:
+            payload = {
+                "project_id": self._project_id,
+                "spans": [self._convert(s) for s in spans],
+            }
+            data = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(
+                self._url, data=data, headers=self._headers, method="POST"
+            )
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                if resp.status >= 300:
+                    logger.warning("blitz export got HTTP %s", resp.status)
+                    return SpanExportResult.FAILURE
+            return SpanExportResult.SUCCESS
+        except Exception:  # noqa: BLE001 - exporting must never raise into the app
+            logger.warning("blitz export failed", exc_info=True)
+            return SpanExportResult.FAILURE
+
+    def shutdown(self) -> None:  # pragma: no cover - nothing to clean up
+        pass
+
+    # -- conversion ----------------------------------------------------------
+
+    def _convert(self, span: ReadableSpan) -> dict:
+        attrs = dict(span.attributes or {})
+        prompt, completion, other = self._split_content(attrs)
+
+        content = None
+        if self._capture_content:
+            content = self._redact_content(
+                {"prompt": prompt, "completion": completion}
+            )
+
+        ctx = span.get_span_context()
+        status = (
+            "error"
+            if span.status is not None and span.status.status_code == StatusCode.ERROR
+            else "ok"
+        )
+
+        return {
+            "trace_id": format(ctx.trace_id, "032x"),
+            "span_id": format(ctx.span_id, "016x"),
+            "parent_span_id": (
+                format(span.parent.span_id, "016x") if span.parent else None
+            ),
+            "name": span.name,
+            "provider": attrs.get("gen_ai.system"),
+            "model": attrs.get("gen_ai.response.model")
+            or attrs.get("gen_ai.request.model"),
+            "input_tokens": _first_int(
+                attrs,
+                "gen_ai.usage.input_tokens",
+                "gen_ai.usage.prompt_tokens",
+                "llm.usage.prompt_tokens",
+            ),
+            "output_tokens": _first_int(
+                attrs,
+                "gen_ai.usage.output_tokens",
+                "gen_ai.usage.completion_tokens",
+                "llm.usage.completion_tokens",
+            ),
+            "start_unix_ns": span.start_time,
+            "end_unix_ns": span.end_time,
+            "status": status,
+            "attributes": _jsonable(other),
+            "content": content,
+        }
+
+    def _split_content(self, attrs: dict):
+        """Pull the indexed prompt/completion attributes
+        (gen_ai.prompt.0.role, gen_ai.prompt.0.content, ...) into ordered lists,
+        leaving everything else in `other`."""
+        prompts: dict[str, dict] = {}
+        completions: dict[str, dict] = {}
+        other: dict = {}
+
+        for key, value in attrs.items():
+            if key.startswith(_PROMPT_PREFIX):
+                idx, _, field = key[len(_PROMPT_PREFIX) :].partition(".")
+                prompts.setdefault(idx, {})[field or "value"] = value
+            elif key.startswith(_COMPLETION_PREFIX):
+                idx, _, field = key[len(_COMPLETION_PREFIX) :].partition(".")
+                completions.setdefault(idx, {})[field or "value"] = value
+            else:
+                other[key] = value
+
+        return _ordered(prompts), _ordered(completions), other
+
+    def _redact_content(self, content: dict) -> dict:
+        for bucket in ("prompt", "completion"):
+            for msg in content.get(bucket, []):
+                if "content" in msg and isinstance(msg["content"], str):
+                    msg["content"] = self._scrub(msg["content"])
+        return content
+
+    def _scrub(self, text: str) -> str:
+        if self._redact:
+            try:
+                text = self._redact(text)
+            except Exception:  # noqa: BLE001
+                logger.warning("blitz redact callable raised", exc_info=True)
+        if self._max and len(text) > self._max:
+            text = text[: self._max] + "…[truncated]"
+        return text
+
+
+def _ordered(indexed: dict[str, dict]) -> list[dict]:
+    return [
+        indexed[i]
+        for i in sorted(indexed, key=lambda x: int(x) if x.isdigit() else 0)
+    ]
+
+
+def _first_int(attrs: dict, *keys: str):
+    for key in keys:
+        if key in attrs and attrs[key] is not None:
+            try:
+                return int(attrs[key])
+            except (TypeError, ValueError):
+                continue
+    return None
+
+
+def _jsonable(obj):
+    """OTel attribute values are already JSON-safe scalars/sequences, but coerce
+    tuples to lists so json.dumps is happy."""
+    if isinstance(obj, dict):
+        return {k: _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    return obj

blitz/_instrument.py

@@ -0,0 +1,52 @@
+"""Wire up the provider instrumentors.
+
+We wrap the maintained openllmetry (Traceloop) instrumentors. Each is optional:
+if the provider SDK (and its instrumentor extra) isn't installed, we skip it
+silently so a customer who only uses Anthropic doesn't need OpenAI installed.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from opentelemetry.sdk.trace import TracerProvider
+
+logger = logging.getLogger("blitz")
+
+
+def instrument_providers(tracer_provider: TracerProvider) -> list[str]:
+    """Instrument every supported provider that is importable. Returns the
+    list of provider names that were successfully instrumented."""
+    instrumented: list[str] = []
+
+    def _try(name: str, importer) -> None:
+        try:
+            instrumentor = importer()
+            instrumentor.instrument(tracer_provider=tracer_provider)
+            instrumented.append(name)
+        except ImportError as exc:
+            logger.debug("blitz: %s instrumentation unavailable (%s)", name, exc)
+        except Exception:  # noqa: BLE001 - never let instrumentation crash the app
+            logger.warning("blitz: failed to instrument %s", name, exc_info=True)
+
+    def _openai():
+        from opentelemetry.instrumentation.openai import OpenAIInstrumentor
+
+        return OpenAIInstrumentor()
+
+    def _anthropic():
+        from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+
+        return AnthropicInstrumentor()
+
+    def _gemini():
+        from opentelemetry.instrumentation.google_generativeai import (
+            GoogleGenerativeAiInstrumentor,
+        )
+
+        return GoogleGenerativeAiInstrumentor()
+
+    _try("openai", _openai)
+    _try("anthropic", _anthropic)
+    _try("gemini", _gemini)
+    return instrumented

blitz_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: blitz-sdk
+Version: 0.1.0
+Summary: Drop-in OpenTelemetry tracing for OpenAI, Anthropic, and Gemini LLM calls. Ships full I/O, token usage, model, latency, and cost to your blitz backend.
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: all
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.33.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.33.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai>=0.33.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.33.0; extra == 'anthropic'
+Provides-Extra: gemini
+Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.33.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.33.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# blitz
+
+Documentation coming.

blitz_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+blitz/__init__.py,sha256=OtxasaffxbQhULDAeTLdJ0XArVT5ySaW5wiqpBqx2mo,3832
+blitz/_exporter.py,sha256=7VrcrvwxJ2kjD2Jj60V0bAWos8KEepbAys39kMeb_J4,6663
+blitz/_instrument.py,sha256=RW_li9hr2SzpXAMNjgFa1NNbxz6zuygDs1C0Xc11Zl4,1742
+blitz_sdk-0.1.0.dist-info/METADATA,sha256=Xng1VHipsdBX4yT0MwgkIAtyN1Rs9yG-qCVeXE4Qa-E,983
+blitz_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+blitz_sdk-0.1.0.dist-info/RECORD,,

blitz_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any