tracely-sdk 0.1.0__py3-none-any.whl

tracely/__init__.py

@@ -0,0 +1,11 @@
+"""TRACELY SDK - Lightweight observability for Python web frameworks."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from tracely.sdk import init, shutdown
+from tracely.tracing import span
+from tracely.logging_api import debug, info, warning, error
+
+__all__ = ["init", "shutdown", "span", "debug", "info", "warning", "error", "__version__"]

tracely/capture.py

@@ -0,0 +1,210 @@
+"""Request/response data capture utilities.
+
+Provides body processing (truncation at 64KB, binary content replacement),
+URL construction, header sanitization, smart data redaction (FR8, FR11),
+and span attribute attachment for full request/response data capture (FR6, FR7).
+
+All public functions are fail-silent — exceptions are caught and logged
+at DEBUG level to satisfy the SDK's zero-crash guarantee.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from tracely.redaction import (
+    get_extra_fields,
+    redact_body,
+    redact_headers,
+    redact_patterns,
+)
+
+logger = logging.getLogger("tracely")
+
+# 64KB body size limit per AC3
+MAX_BODY_SIZE: int = 64 * 1024
+
+# Binary content type prefixes — bodies with these types are replaced
+# with a placeholder rather than captured verbatim.
+_BINARY_PREFIXES: tuple[str, ...] = (
+    "image/",
+    "video/",
+    "audio/",
+    "application/octet-stream",
+    "application/zip",
+    "application/gzip",
+    "application/pdf",
+    "application/x-tar",
+    "application/x-bzip2",
+    "application/x-7z-compressed",
+    "application/vnd.",
+    "font/",
+)
+
+
+def is_binary_content_type(content_type: str) -> bool:
+    """Return True if the content type represents binary data.
+
+    Matching is case-insensitive and ignores parameters (charset, etc.).
+    """
+    if not content_type:
+        return False
+    # Normalize: lowercase, strip parameters for prefix check
+    ct_lower = content_type.lower().split(";")[0].strip()
+    return ct_lower.startswith(_BINARY_PREFIXES)
+
+
+def process_body(
+    body: bytes | str | None,
+    content_type: str,
+) -> tuple[str, dict[str, str]]:
+    """Process a request or response body for span storage.
+
+    Returns:
+        A tuple of (processed_body_str, metadata_dict).
+        metadata_dict may contain:
+          - http.body.original_length: original byte length (if truncated or binary)
+          - http.body.truncated: "true" (if truncated)
+
+    Rules (per AC3/AC4):
+        - Bodies > 64KB are truncated with a ``[truncated]`` marker.
+        - Binary content types are replaced with ``[binary: <ct>, <size> bytes]``.
+        - Empty/None bodies return empty string with no metadata.
+    """
+    if body is None:
+        return "", {}
+
+    if isinstance(body, str):
+        raw = body.encode("utf-8", errors="replace")
+    else:
+        raw = body
+
+    if len(raw) == 0:
+        return "", {}
+
+    meta: dict[str, str] = {}
+
+    # Binary content type — replace with placeholder (AC4)
+    if is_binary_content_type(content_type or ""):
+        meta["body.original_length"] = str(len(raw))
+        return f"[binary: {content_type}, {len(raw)} bytes]", meta
+
+    # Truncation at 64KB (AC3)
+    if len(raw) > MAX_BODY_SIZE:
+        meta["body.original_length"] = str(len(raw))
+        meta["body.truncated"] = "true"
+        truncated = raw[:MAX_BODY_SIZE].decode("utf-8", errors="replace")
+        return truncated + "[truncated]", meta
+
+    return raw.decode("utf-8", errors="replace"), meta
+
+
+def build_url(scheme: str, host: str, path: str, query_string: str) -> str:
+    """Construct a full URL from its components.
+
+    Args:
+        scheme: URL scheme (http, https).
+        host: Hostname, optionally with port (e.g. "example.com:8080").
+        path: Request path (e.g. "/api/users").
+        query_string: Raw query string without leading '?'.
+
+    Returns:
+        Full URL string.
+    """
+    if not path:
+        path = "/"
+    elif not path.startswith("/"):
+        path = "/" + path
+
+    url = f"{scheme}://{host}{path}"
+    if query_string:
+        url = f"{url}?{query_string}"
+    return url
+
+
+def sanitize_headers(
+    headers: dict[str, str] | list[tuple[bytes, bytes]] | None,
+) -> str:
+    """Convert headers to a JSON string for span attribute storage.
+
+    Applies smart redaction (FR8) to sensitive header values before
+    serialization.  The original headers object is never mutated.
+
+    Accepts:
+        - dict[str, str]: Already key-value pairs.
+        - list[tuple[bytes, bytes]]: ASGI-style raw header pairs.
+        - None: Returns empty JSON object.
+
+    Returns:
+        JSON string representation of headers with sensitive values redacted.
+    """
+    if headers is None:
+        return "{}"
+
+    # redact_headers returns a new dict — original data is never modified
+    redacted = redact_headers(headers)
+    if not redacted:
+        return "{}"
+    return json.dumps(redacted, default=str)
+
+
+def capture_request_data(
+    span: Any,
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str] | list[tuple[bytes, bytes]] | None = None,
+    body: bytes | str | None = None,
+    content_type: str = "",
+    query_params: str = "",
+) -> None:
+    """Attach request data as span attributes (FR6).
+
+    Fail-silent — never raises.
+    """
+    try:
+        span.set_attribute("http.method", method)
+        span.set_attribute("http.url", url)
+        span.set_attribute("http.request.headers", sanitize_headers(headers))
+
+        processed_body, meta = process_body(body, content_type)
+        # Apply smart data redaction (FR8) — field-name + pattern-based
+        redacted_body = redact_body(processed_body, extra_fields=get_extra_fields())
+        redacted_body = redact_patterns(redacted_body)
+        span.set_attribute("http.request.body", redacted_body)
+        for key, value in meta.items():
+            span.set_attribute(f"http.request.{key}", value)
+
+        if query_params:
+            span.set_attribute("http.request.query", query_params)
+    except Exception:
+        logger.debug("Error capturing request data", exc_info=True)
+
+
+def capture_response_data(
+    span: Any,
+    *,
+    status_code: int,
+    headers: dict[str, str] | list[tuple[bytes, bytes]] | None = None,
+    body: bytes | str | None = None,
+    content_type: str = "",
+) -> None:
+    """Attach response data as span attributes (FR7).
+
+    Fail-silent — never raises.
+    """
+    try:
+        span.set_attribute("http.status_code", str(status_code))
+        span.set_attribute("http.response.headers", sanitize_headers(headers))
+
+        processed_body, meta = process_body(body, content_type or "")
+        # Apply smart data redaction (FR8) — field-name + pattern-based
+        redacted_body = redact_body(processed_body, extra_fields=get_extra_fields())
+        redacted_body = redact_patterns(redacted_body)
+        span.set_attribute("http.response.body", redacted_body)
+        for key, value in meta.items():
+            span.set_attribute(f"http.response.{key}", value)
+    except Exception:
+        logger.debug("Error capturing response data", exc_info=True)

tracely/config.py

@@ -0,0 +1,39 @@
+"""Configuration management for the TRACELY SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+DEFAULT_ENDPOINT = "https://i.tracely.sh"
+
+
+@dataclass
+class TracelyConfig:
+    """SDK configuration. Reads from env vars or accepts explicit values."""
+
+    api_key: str | None = None
+    environment: str | None = None
+    endpoint: str = DEFAULT_ENDPOINT
+    service_name: str | None = None
+    service_version: str | None = None
+    redact_fields: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def from_env(cls) -> TracelyConfig:
+        """Create config from environment variables."""
+        raw_fields = os.environ.get("TRACELY_REDACT_FIELDS", "")
+        redact_fields = frozenset(
+            f.strip().lower() for f in raw_fields.split(",") if f.strip()
+        )
+        return cls(
+            api_key=os.environ.get("TRACELY_API_KEY"),
+            environment=os.environ.get("ENVIRONMENT"),
+            endpoint=os.environ.get("TRACELY_ENDPOINT", DEFAULT_ENDPOINT),
+            redact_fields=redact_fields,
+        )
+
+    @property
+    def enabled(self) -> bool:
+        """SDK is enabled only when an API key is present."""
+        return self.api_key is not None

tracely/context.py

@@ -0,0 +1,55 @@
+"""Context propagation for active span tracking.
+
+Uses Python's contextvars for async-safe, per-task span tracking.
+Each async task or thread gets its own active span, preventing
+cross-request contamination.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING, Generator
+
+if TYPE_CHECKING:
+    from tracely.span import Span
+
+_current_span: ContextVar[Span | None] = ContextVar("_current_span", default=None)
+
+
+def get_current_span() -> Span | None:
+    """Return the currently active span, or None if no span is active."""
+    return _current_span.get()
+
+
+def set_current_span(span: Span | None, token: Token[Span | None] | None = None) -> Token[Span | None]:
+    """Set the currently active span.
+
+    Args:
+        span: The span to set as active, or None to clear.
+        token: Optional token from a previous set_current_span call
+               to restore the prior value.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    if token is not None:
+        _current_span.reset(token)
+        return token
+    return _current_span.set(span)
+
+
+@contextmanager
+def _span_context(span: Span) -> Generator[Span, None, None]:
+    """Context manager that sets span as active and restores the previous span on exit.
+
+    Usage:
+        with _span_context(my_span):
+            # my_span is the active span here
+        # previous span (or None) is restored
+    """
+    token = _current_span.set(span)
+    try:
+        yield span
+    finally:
+        _current_span.reset(token)

tracely/detection.py

@@ -0,0 +1,49 @@
+"""Framework auto-detection for the TRACELY SDK.
+
+Detects installed web frameworks (FastAPI, Django, Flask) and database
+libraries (SQLAlchemy, pymongo) using importlib.util.find_spec() — a
+non-importing check that avoids side effects.
+
+Detection priority: FastAPI > Django > Flask.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from importlib.util import find_spec
+
+logger = logging.getLogger("tracely")
+
+DETECTION_ORDER = ("fastapi", "django", "flask")
+
+
+@dataclass
+class FrameworkInfo:
+    """Detected framework and companion libraries."""
+
+    name: str
+    has_sqlalchemy: bool = False
+    has_pymongo: bool = False
+
+
+def detect_framework() -> FrameworkInfo | None:
+    """Detect installed web framework and database libraries.
+
+    Returns FrameworkInfo for the highest-priority detected framework,
+    or None if no supported framework is found.
+
+    Never raises — all exceptions are caught silently (FR10).
+    """
+    try:
+        for framework_name in DETECTION_ORDER:
+            if find_spec(framework_name) is not None:
+                return FrameworkInfo(
+                    name=framework_name,
+                    has_sqlalchemy=find_spec("sqlalchemy") is not None,
+                    has_pymongo=find_spec("pymongo") is not None,
+                )
+        return None
+    except Exception:
+        logger.debug("TRACELY framework detection failed", exc_info=True)
+        return None

tracely/exporter.py

@@ -0,0 +1,120 @@
+"""Batch span exporter with background flush loop (FR9, AC3).
+
+Drains SpanBuffer on a timer interval or batch-size threshold,
+serializes to OTLP protobuf, and sends via HttpTransport.
+
+Uses a daemon thread with its own event loop so it works in both
+sync (Flask/Django) and async (FastAPI) host applications.
+
+All operations are fail-silent — never crashes the host application.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import TYPE_CHECKING
+
+from tracely.otlp import serialize_spans
+
+if TYPE_CHECKING:
+    from tracely.transport import HttpTransport, SpanBuffer
+
+logger = logging.getLogger("tracely")
+
+DEFAULT_FLUSH_INTERVAL = 1.0  # seconds (AC3)
+
+
+class BatchSpanExporter:
+    """Background exporter that batch-sends buffered spans via OTLP/HTTP.
+
+    Runs in a daemon thread with its own asyncio event loop so that
+    SDK init/shutdown can be called from any context (sync or async).
+
+    Args:
+        buffer: SpanBuffer to drain spans from.
+        transport: HttpTransport to send OTLP protobuf bytes.
+        flush_interval: Seconds between flush cycles (default 1.0 per AC3).
+    """
+
+    def __init__(
+        self,
+        buffer: SpanBuffer,
+        transport: HttpTransport,
+        flush_interval: float = DEFAULT_FLUSH_INTERVAL,
+    ) -> None:
+        self._buffer = buffer
+        self._transport = transport
+        self._flush_interval = flush_interval
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+        self._notify_event = threading.Event()
+
+    def start(self) -> None:
+        """Start the background export thread."""
+        self._stop_event.clear()
+        self._notify_event.clear()
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._run, daemon=True, name="tracely-exporter",
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the background thread and drain remaining spans.
+
+        Blocks until the thread exits (up to 5 seconds).
+        The thread performs a final flush before exiting.
+        """
+        self._stop_event.set()
+        self._notify_event.set()  # Wake up if sleeping
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=5.0)
+
+    def notify(self) -> None:
+        """Wake the export loop (e.g. when batch threshold is reached)."""
+        self._notify_event.set()
+
+    def _run(self) -> None:
+        """Background loop running in daemon thread."""
+        asyncio.set_event_loop(self._loop)
+        try:
+            while not self._stop_event.is_set():
+                # Wait for interval or notification, whichever comes first
+                self._notify_event.wait(timeout=self._flush_interval)
+                self._notify_event.clear()
+
+                if self._stop_event.is_set():
+                    break
+
+                self._loop.run_until_complete(self._flush())
+
+            # Final drain before thread exits
+            self._loop.run_until_complete(self._flush())
+        except Exception:
+            logger.debug("TRACELY: Error in exporter thread", exc_info=True)
+        finally:
+            self._loop.close()
+
+    async def _flush(self) -> None:
+        """Drain buffer, serialize to OTLP protobuf, send via transport."""
+        spans = self._buffer.flush()
+        if not spans:
+            return
+
+        try:
+            payload = serialize_spans(spans)
+        except Exception:
+            logger.debug("TRACELY: Error serializing spans to OTLP", exc_info=True)
+            return
+
+        try:
+            success = await self._transport.send(payload)
+            if not success:
+                logger.debug(
+                    "TRACELY: Batch export failed for %d spans", len(spans),
+                )
+        except Exception:
+            logger.debug("TRACELY: Unexpected error in batch export", exc_info=True)

tracely/instrumentation/__init__.py

@@ -0,0 +1,47 @@
+"""Instrumentor registry and factory."""
+
+from __future__ import annotations
+
+import logging
+
+from tracely.detection import FrameworkInfo
+from tracely.instrumentation.base import BaseInstrumentor
+
+logger = logging.getLogger("tracely")
+
+# Lazy-loaded instrumentor classes keyed by framework name.
+_REGISTRY: dict[str, str] = {
+    "fastapi": "tracely.instrumentation.fastapi_inst.FastAPIInstrumentor",
+    "django": "tracely.instrumentation.django_inst.DjangoInstrumentor",
+    "flask": "tracely.instrumentation.flask_inst.FlaskInstrumentor",
+}
+
+
+def get_instrumentor(framework_info: FrameworkInfo) -> BaseInstrumentor | None:
+    """Return the instrumentor for the given framework, or None if unknown.
+
+    Uses lazy import to avoid pulling in framework-specific code until needed.
+    Never raises — returns None on any failure.
+    """
+    qualname = _REGISTRY.get(framework_info.name)
+    if qualname is None:
+        logger.debug("No instrumentor registered for %s", framework_info.name)
+        return None
+
+    try:
+        module_path, class_name = qualname.rsplit(".", 1)
+        import importlib
+
+        module = importlib.import_module(module_path)
+        cls = getattr(module, class_name)
+        return cls(framework_info)
+    except Exception:
+        logger.debug(
+            "Failed to load instrumentor for %s",
+            framework_info.name,
+            exc_info=True,
+        )
+        return None
+
+
+__all__ = ["BaseInstrumentor", "get_instrumentor"]

tracely/instrumentation/base.py

@@ -0,0 +1,30 @@
+"""Base instrumentor interface for framework auto-instrumentation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from tracely.detection import FrameworkInfo
+
+
+class BaseInstrumentor(ABC):
+    """Abstract base class for framework-specific instrumentors.
+
+    Subclasses implement activate() to install hooks/middleware and
+    deactivate() to remove them on shutdown.
+    """
+
+    def __init__(self, framework_info: FrameworkInfo) -> None:
+        self._framework_info = framework_info
+
+    @property
+    def framework_info(self) -> FrameworkInfo:
+        return self._framework_info
+
+    @abstractmethod
+    def activate(self) -> None:
+        """Install instrumentation hooks for the detected framework."""
+
+    @abstractmethod
+    def deactivate(self) -> None:
+        """Remove instrumentation hooks (cleanup on shutdown)."""