tracely-sdk 0.1.0__py3-none-any.whl

tracely/redaction.py

@@ -0,0 +1,196 @@
+"""Smart data redaction for the TRACELY SDK (FR8, FR11, NFR11).
+
+Provides field-name based redaction for JSON bodies, header value
+redaction for sensitive headers, and pattern-based redaction for
+credit card numbers, email addresses, and SSNs.
+
+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
+import re
+from typing import Any
+
+logger = logging.getLogger("tracely")
+
+# Default sensitive field names (AC1) — matched case-insensitively
+SENSITIVE_FIELDS: frozenset[str] = frozenset({
+    "password",
+    "secret",
+    "token",
+    "authorization",
+    "api_key",
+    "credit_card",
+    "ssn",
+})
+
+# Default sensitive header names (AC2) — matched case-insensitively
+SENSITIVE_HEADERS: frozenset[str] = frozenset({
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+})
+
+REDACTED: str = "[REDACTED]"
+
+# Pattern-based redaction (AC3) — compiled regexes for performance
+# Credit card: 16 digits, optionally separated by dashes or spaces
+_CC_PATTERN: re.Pattern[str] = re.compile(
+    r"\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b"
+)
+# SSN: XXX-XX-XXXX format
+_SSN_PATTERN: re.Pattern[str] = re.compile(
+    r"\b\d{3}-\d{2}-\d{4}\b"
+)
+# Email: standard email pattern
+_EMAIL_PATTERN: re.Pattern[str] = re.compile(
+    r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
+)
+
+
+# Module-level state for custom redaction fields (set via configure_redaction)
+_extra_fields: frozenset[str] = frozenset()
+
+
+def configure_redaction(
+    *,
+    extra_fields: frozenset[str] = frozenset(),
+) -> None:
+    """Configure module-level redaction settings.
+
+    Called by SDK init to propagate ``TRACELY_REDACT_FIELDS`` config.
+
+    Args:
+        extra_fields: Additional field names to redact (additive to defaults).
+    """
+    global _extra_fields
+    _extra_fields = extra_fields
+
+
+def get_extra_fields() -> frozenset[str]:
+    """Return the currently configured extra redaction fields."""
+    return _extra_fields
+
+
+def _redact_value(obj: Any, sensitive: frozenset[str]) -> Any:
+    """Recursively redact sensitive field values in a parsed JSON structure.
+
+    Field name matching is case-insensitive.  Field names are preserved;
+    only values are replaced with ``[REDACTED]``.
+    """
+    if isinstance(obj, dict):
+        return {
+            key: REDACTED if key.lower() in sensitive else _redact_value(value, sensitive)
+            for key, value in obj.items()
+        }
+    if isinstance(obj, list):
+        return [_redact_value(item, sensitive) for item in obj]
+    return obj
+
+
+def redact_body(
+    body: str,
+    *,
+    extra_fields: frozenset[str] | None = None,
+) -> str:
+    """Redact sensitive field values in a JSON body string.
+
+    Args:
+        body: The body string (may or may not be valid JSON).
+        extra_fields: Additional field names to redact (merged with defaults).
+
+    Returns:
+        The body with sensitive field values replaced by ``[REDACTED]``,
+        or the original body unchanged if it is not valid JSON.
+    """
+    if not body:
+        return body
+
+    sensitive = SENSITIVE_FIELDS
+    if extra_fields:
+        sensitive = SENSITIVE_FIELDS | extra_fields
+
+    try:
+        parsed = json.loads(body)
+    except (json.JSONDecodeError, ValueError):
+        return body
+
+    try:
+        redacted = _redact_value(parsed, sensitive)
+        # Only re-serialize if redaction actually changed something;
+        # otherwise preserve original body formatting exactly.
+        if redacted == parsed:
+            return body
+        return json.dumps(redacted)
+    except Exception:
+        logger.debug("Error during body redaction", exc_info=True)
+        return body
+
+
+def redact_headers(
+    headers: dict[str, str] | list[tuple[bytes, bytes]] | None,
+) -> dict[str, str]:
+    """Redact sensitive header values.
+
+    Args:
+        headers: Headers as dict, ASGI-style byte tuples, or None.
+
+    Returns:
+        A new dict with sensitive header values replaced by ``[REDACTED]``.
+        Non-sensitive headers are preserved as-is.
+    """
+    if headers is None:
+        return {}
+
+    try:
+        if isinstance(headers, dict):
+            if not headers:
+                return {}
+            return {
+                key: REDACTED if key.lower() in SENSITIVE_HEADERS else value
+                for key, value in headers.items()
+            }
+
+        # ASGI-style list of (name_bytes, value_bytes) tuples
+        result: dict[str, str] = {}
+        for name, value in headers:
+            key = name.decode("utf-8", errors="replace") if isinstance(name, bytes) else str(name)
+            val = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else str(value)
+            result[key] = REDACTED if key.lower() in SENSITIVE_HEADERS else val
+        return result
+    except Exception:
+        logger.debug("Error during header redaction", exc_info=True)
+        return {}
+
+
+def redact_patterns(text: str) -> str:
+    """Apply pattern-based redaction for credit card, email, and SSN.
+
+    Scans the input text and replaces matches with typed placeholders:
+    ``[REDACTED:credit_card]``, ``[REDACTED:email]``, ``[REDACTED:ssn]``.
+
+    Args:
+        text: The text string to scan.
+
+    Returns:
+        The text with matched patterns replaced, or the original text
+        if no patterns are found or an error occurs.
+    """
+    if not text:
+        return text
+
+    try:
+        # Order matters: SSN before CC to avoid SSN being partially matched
+        # as a CC sub-pattern.  SSN is more specific (XXX-XX-XXXX).
+        result = _SSN_PATTERN.sub("[REDACTED:ssn]", text)
+        result = _CC_PATTERN.sub("[REDACTED:credit_card]", result)
+        result = _EMAIL_PATTERN.sub("[REDACTED:email]", result)
+        return result
+    except Exception:
+        logger.debug("Error during pattern redaction", exc_info=True)
+        return text

tracely/sdk.py

@@ -0,0 +1,192 @@
+"""Core SDK initialization and lifecycle."""
+
+from __future__ import annotations
+
+import logging
+
+from tracely.config import TracelyConfig
+from tracely.detection import FrameworkInfo, detect_framework
+from tracely.exporter import BatchSpanExporter
+from tracely.instrumentation import get_instrumentor
+from tracely.instrumentation.base import BaseInstrumentor
+from tracely.redaction import configure_redaction
+from tracely.span_processor import SpanProcessor, set_processor
+from tracely.transport import HttpTransport, SpanBuffer
+
+logger = logging.getLogger("tracely")
+
+_instance: TracelySdk | None = None
+
+
+class TracelySdk:
+    """Singleton managing SDK state and lifecycle."""
+
+    def __init__(
+        self,
+        config: TracelyConfig,
+        framework_info: FrameworkInfo | None = None,
+        instrumentor: BaseInstrumentor | None = None,
+        buffer: SpanBuffer | None = None,
+        transport: HttpTransport | None = None,
+        processor: SpanProcessor | None = None,
+        exporter: BatchSpanExporter | None = None,
+    ) -> None:
+        self.config = config
+        self.enabled = config.enabled
+        self.framework_info = framework_info
+        self.instrumentor = instrumentor
+        self.buffer = buffer
+        self.transport = transport
+        self.processor = processor
+        self.exporter = exporter
+
+    def shutdown(self) -> None:
+        """Flush buffers, deactivate instrumentation, release resources."""
+        # Stop batch exporter (flushes remaining spans)
+        if self.exporter is not None:
+            try:
+                self.exporter.stop()
+            except Exception:
+                logger.debug("Error stopping exporter", exc_info=True)
+
+        # Deactivate instrumentation
+        if self.instrumentor is not None:
+            try:
+                self.instrumentor.deactivate()
+            except Exception:
+                logger.debug("Error deactivating instrumentor", exc_info=True)
+
+        # Clear global processor
+        set_processor(None)
+
+        self.enabled = False
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    environment: str | None = None,
+    endpoint: str | None = None,
+    service_name: str | None = None,
+    service_version: str | None = None,
+) -> None:
+    """Initialize the TRACELY SDK.
+
+    Reads configuration from environment variables by default.
+    Explicit parameters override env vars.
+
+    When enabled (API key present), creates the full export pipeline:
+    SpanBuffer → SpanProcessor → BatchSpanExporter → HttpTransport → OTLP/HTTP
+
+    Args:
+        api_key: Override TRACELY_API_KEY env var.
+        environment: Override ENVIRONMENT env var.
+        endpoint: Override TRACELY_ENDPOINT env var.
+        service_name: Label for this service (e.g., "api", "celery-worker").
+        service_version: Version string for this service.
+    """
+    global _instance
+
+    if _instance is not None:
+        return
+
+    config = TracelyConfig.from_env()
+
+    if api_key is not None:
+        config.api_key = api_key
+    if environment is not None:
+        config.environment = environment
+    if endpoint is not None:
+        config.endpoint = endpoint
+    if service_name is not None:
+        config.service_name = service_name
+    if service_version is not None:
+        config.service_version = service_version
+
+    # Configure smart data redaction with custom fields from env (FR8, FR11)
+    configure_redaction(extra_fields=config.redact_fields)
+
+    if not config.enabled:
+        logger.warning(
+            "TRACELY_API_KEY not set. SDK is disabled — "
+            "no telemetry will be collected or sent."
+        )
+
+    # Detect framework (always, even when disabled — for diagnostics)
+    framework_info = detect_framework()
+
+    # Create export pipeline when SDK is enabled
+    buffer: SpanBuffer | None = None
+    transport: HttpTransport | None = None
+    processor: SpanProcessor | None = None
+    exporter: BatchSpanExporter | None = None
+
+    if config.enabled and config.api_key:
+        buffer = SpanBuffer()
+        transport = HttpTransport(
+            endpoint=config.endpoint,
+            api_key=config.api_key,
+        )
+        exporter = BatchSpanExporter(buffer=buffer, transport=transport)
+        processor = SpanProcessor(buffer=buffer, on_buffer_ready=exporter.notify)
+
+        # Register global processor for middleware to use
+        set_processor(processor)
+
+        # Start background export thread
+        try:
+            exporter.start()
+        except Exception:
+            logger.debug("Error starting batch exporter", exc_info=True)
+
+    # Activate instrumentation only when SDK is enabled
+    instrumentor: BaseInstrumentor | None = None
+    if config.enabled and framework_info is not None:
+        instrumentor = get_instrumentor(framework_info)
+        if instrumentor is not None:
+            try:
+                instrumentor.activate()
+            except Exception:
+                logger.debug("Error activating instrumentor", exc_info=True)
+                instrumentor = None
+
+    if framework_info is not None:
+        logger.info("TRACELY: Detected framework: %s", framework_info.name)
+    else:
+        logger.info(
+            "TRACELY: No supported framework detected. "
+            "Use manual instrumentation for custom setups."
+        )
+
+    _instance = TracelySdk(
+        config=config,
+        framework_info=framework_info,
+        instrumentor=instrumentor,
+        buffer=buffer,
+        transport=transport,
+        processor=processor,
+        exporter=exporter,
+    )
+
+
+def shutdown() -> None:
+    """Gracefully shut down the SDK, flushing any buffered data."""
+    global _instance
+
+    if _instance is not None:
+        _instance.shutdown()
+        _instance = None
+
+
+def _sdk_instance() -> TracelySdk | None:
+    """Return the current SDK instance (for testing)."""
+    return _instance
+
+
+def _reset() -> None:
+    """Reset SDK state (for testing only)."""
+    global _instance
+    if _instance is not None:
+        _instance.shutdown()
+    _instance = None
+    set_processor(None)

tracely/span.py

@@ -0,0 +1,168 @@
+"""Span model and trace ID generation for structured tracing."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Callable
+
+logger = logging.getLogger("tracely")
+
+
+def generate_trace_id() -> str:
+    """Generate a unique trace ID (32 lowercase hex characters)."""
+    return os.urandom(16).hex()
+
+
+def generate_span_id() -> str:
+    """Generate a unique span ID (16 lowercase hex characters)."""
+    return os.urandom(8).hex()
+
+
+class Span:
+    """Represents a single span in a distributed trace.
+
+    A root span has no parent. Child spans inherit trace_id from
+    their parent and set parent_span_id accordingly.
+
+    Args:
+        name: Human-readable operation name (e.g., "GET /api/users").
+        parent: Optional parent span — child inherits trace_id.
+        span_type: "span" (default) or "pending_span" for AR3 pattern.
+        kind: Span kind: INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER.
+        service_name: Name of the service producing this span.
+        on_end: Callback invoked when span ends, receiving the span.
+    """
+
+    __slots__ = (
+        "trace_id",
+        "span_id",
+        "parent_span_id",
+        "name",
+        "span_type",
+        "kind",
+        "service_name",
+        "start_time",
+        "end_time",
+        "duration_ms",
+        "status_code",
+        "status_message",
+        "attributes",
+        "events",
+        "_on_end",
+        "_ended",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        parent: Span | None = None,
+        span_type: str = "span",
+        kind: str = "INTERNAL",
+        service_name: str | None = None,
+        on_end: Callable[[Span], None] | None = None,
+    ) -> None:
+        if parent is not None:
+            self.trace_id = parent.trace_id
+            self.parent_span_id = parent.span_id
+        else:
+            self.trace_id = generate_trace_id()
+            self.parent_span_id: str | None = None
+
+        self.span_id = generate_span_id()
+        self.name = name
+        self.span_type = span_type
+        self.kind = kind
+        self.service_name = service_name
+        self.start_time: float = time.time()
+        self.end_time: float | None = None
+        self.duration_ms: float | None = None
+        self.status_code: str = "UNSET"
+        self.status_message: str = ""
+        self.attributes: dict[str, str] = {}
+        self.events: list[dict[str, Any]] = []
+        self._on_end = on_end
+        self._ended = False
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Attach a key-value attribute to the span.
+
+        Values are converted to strings. No-op if span is already ended.
+        """
+        if self._ended:
+            return
+        self.attributes[key] = str(value)
+
+    def add_event(
+        self,
+        message: str,
+        *,
+        level: str = "INFO",
+        attributes: dict[str, str] | None = None,
+    ) -> None:
+        """Add a log event to this span.
+
+        No-op if span is already ended.
+
+        Args:
+            message: Human-readable event message.
+            level: Log level (DEBUG, INFO, WARNING, ERROR).
+            attributes: Optional key-value metadata for this event.
+        """
+        if self._ended:
+            return
+        self.events.append({
+            "timestamp": time.time(),
+            "level": level,
+            "message": message,
+            "attributes": dict(attributes) if attributes else {},
+        })
+
+    def set_status(self, code: str, message: str = "") -> None:
+        """Set the span's status code and optional message.
+
+        No-op if span is already ended.
+        """
+        if self._ended:
+            return
+        self.status_code = code
+        self.status_message = message
+
+    def end(self) -> None:
+        """Finalize the span, computing duration and invoking on_end callback.
+
+        Idempotent — second call is a no-op.
+        """
+        if self._ended:
+            return
+        self._ended = True
+        self.end_time = time.time()
+        self.duration_ms = (self.end_time - self.start_time) * 1000
+
+        if self._on_end is not None:
+            try:
+                self._on_end(self)
+            except Exception:
+                logger.debug("Error in span on_end callback", exc_info=True)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the span to a dict suitable for transport."""
+        return {
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "parent_span_id": self.parent_span_id,
+            "span_name": self.name,
+            "span_type": self.span_type,
+            "kind": self.kind,
+            "service_name": self.service_name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration_ms": self.duration_ms,
+            "status_code": self.status_code,
+            "status_message": self.status_message,
+            "attributes": dict(self.attributes),
+            "events": list(self.events),
+            "event_count": len(self.events),
+        }

tracely/span_processor.py

@@ -0,0 +1,110 @@
+"""Span processor for pending span pattern (AR3).
+
+Exports spans to SpanBuffer on both start (pending_span) and end (span),
+enabling real-time dashboard updates for in-progress requests.
+
+Also provides a global processor registry so middleware and the tracing API
+can call on_start/on_end without direct references to the processor instance.
+
+All operations are fail-silent — never crashes the host application.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from tracely.span import Span
+    from tracely.transport import SpanBuffer
+
+logger = logging.getLogger("tracely")
+
+# Global processor instance, set by SDK init()
+_processor: SpanProcessor | None = None
+
+
+def set_processor(processor: SpanProcessor | None) -> None:
+    """Register the global span processor (called by SDK init)."""
+    global _processor
+    _processor = processor
+
+
+def get_processor() -> SpanProcessor | None:
+    """Get the global span processor."""
+    return _processor
+
+
+def on_span_start(span: Span) -> None:
+    """Notify the global processor that a span has started.
+
+    No-op if no processor is registered (SDK disabled).
+    """
+    proc = _processor
+    if proc is not None:
+        proc.on_start(span)
+
+
+def on_span_end(span: Span) -> None:
+    """Notify the global processor that a span has ended.
+
+    No-op if no processor is registered (SDK disabled).
+    Suitable as Span's on_end callback.
+    """
+    proc = _processor
+    if proc is not None:
+        proc.on_end(span)
+
+
+class SpanProcessor:
+    """Processes span lifecycle events and enqueues them to SpanBuffer.
+
+    Args:
+        buffer: SpanBuffer to enqueue span dicts into.
+        on_buffer_ready: Optional callback invoked when the buffer reaches
+            the batch threshold (e.g. to wake the exporter).
+    """
+
+    def __init__(
+        self,
+        buffer: SpanBuffer,
+        on_buffer_ready: Callable[[], None] | None = None,
+    ) -> None:
+        self._buffer = buffer
+        self._on_buffer_ready = on_buffer_ready
+
+    def _maybe_notify(self) -> None:
+        """Call the notify callback if the buffer has reached batch threshold."""
+        if self._on_buffer_ready is not None and self._buffer.is_ready:
+            try:
+                self._on_buffer_ready()
+            except Exception:
+                logger.debug("Error in buffer-ready callback", exc_info=True)
+
+    def on_start(self, span: Span) -> None:
+        """Export a pending_span when a span starts.
+
+        Enqueues a snapshot of the span with span_type="pending_span"
+        so the dashboard can show in-progress requests.
+        """
+        try:
+            d = span.to_dict()
+            d["span_type"] = "pending_span"
+            self._buffer.enqueue(d)
+            self._maybe_notify()
+        except Exception:
+            logger.debug("Error in SpanProcessor.on_start", exc_info=True)
+
+    def on_end(self, span: Span) -> None:
+        """Export the final span when a span ends.
+
+        Enqueues the completed span with span_type="span".
+        Suitable as Span's on_end callback.
+        """
+        try:
+            d = span.to_dict()
+            d["span_type"] = "span"
+            self._buffer.enqueue(d)
+            self._maybe_notify()
+        except Exception:
+            logger.debug("Error in SpanProcessor.on_end", exc_info=True)