debugbundle-python 0.1.0__py3-none-any.whl

debugbundle/__init__.py

@@ -0,0 +1,165 @@
+"""DebugBundle Python SDK."""
+
+import asyncio
+import importlib
+import logging
+from collections.abc import Callable, Mapping
+from contextvars import Token
+from typing import Any
+
+from .config import RemoteProbeDirective
+from .core import ConfigFetchResponse, DebugBundleSdk
+from .relay import BrowserRelayAcceptedBatch, BrowserRelayHandler, BrowserRelayResponse
+
+_sdk = DebugBundleSdk()
+
+
+def init(
+    project_token: str,
+    environment: str | None = None,
+    service: str | None = None,
+    enabled: bool = True,
+    redact_fields: list[str] | None = None,
+    sample_rate: float = 1.0,
+    batch_size: int = 25,
+    flush_interval: float = 5.0,
+    endpoint: str = "https://api.debugbundle.com/v1/events",
+    log_level: str = "warning",
+    max_probe_labels: int = 50,
+    max_probe_entries_per_label: int = 10,
+    probe_flush_on_error: bool = True,
+    fetch_impl: Callable[[str, dict[str, object]], ConfigFetchResponse] | None = None,
+    on_diagnostic: Callable[[dict[str, object]], None] | None = None,
+    probes_poll_interval: int = 60_000,
+) -> None:
+    _sdk.init(
+        project_token=project_token,
+        environment=environment,
+        service=service,
+        enabled=enabled,
+        redact_fields=redact_fields,
+        sample_rate=sample_rate,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+        endpoint=endpoint,
+        log_level=log_level,
+        max_probe_labels=max_probe_labels,
+        max_probe_entries_per_label=max_probe_entries_per_label,
+        probe_flush_on_error=probe_flush_on_error,
+        fetch_impl=fetch_impl,
+        on_diagnostic=on_diagnostic,
+        probes_poll_interval=probes_poll_interval,
+    )
+
+
+def capture_exception(error: BaseException, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_exception(error, context=context)
+
+
+def capture_error(error: BaseException, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_error(error, context=context)
+
+
+def capture_log(message: str, level: str = "warning", context: dict[str, object] | None = None) -> None:
+    _sdk.capture_log(message, level=level, context=context)
+
+
+def capture_request(
+    request: Mapping[str, object],
+    response: Mapping[str, object] | None = None,
+    context: Mapping[str, object] | None = None,
+) -> None:
+    _sdk.capture_request(request, response=response, context=context)
+
+
+def capture_message(message: str, level: str | None = None, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_message(message, level=level, context=context)
+
+
+def set_context(key: str, value: object) -> None:
+    _sdk.set_context(key, value)
+
+
+def flush() -> None:
+    _sdk.flush()
+
+
+def get_status() -> str:
+    return _sdk.status
+
+
+def get_last_event_at() -> float | None:
+    return _sdk.last_event_at
+
+
+def probe(label: str, data: object | Callable[[], object], opts: Mapping[str, object] | None = None) -> None:
+    _sdk.probe(label, data, opts=opts)
+
+
+def capture_exceptions() -> None:
+    _sdk.capture_exceptions()
+
+
+def capture_logging(logger: logging.Logger | None = None) -> None:
+    _sdk.capture_logging(logger=logger)
+
+
+def capture_async(loop: asyncio.AbstractEventLoop | None = None) -> None:
+    _sdk.capture_async(loop=loop)
+
+
+def begin_request(request: dict) -> object:
+    return _sdk.begin_request(request)
+
+
+def end_request(token: Token[list[RemoteProbeDirective] | None]) -> None:
+    _sdk.end_request(token)
+
+
+_OPTIONAL_EXPORTS = {
+    "DebugBundleDjangoMiddleware": (".integrations.django", "DebugBundleDjangoMiddleware"),
+    "DebugBundleFastAPIMiddleware": (".integrations.fastapi", "DebugBundleFastAPIMiddleware"),
+    "create_django_relay_view": (".integrations.relay_django", "create_django_relay_view"),
+    "create_fastapi_relay_handler": (".integrations.relay_fastapi", "create_fastapi_relay_handler"),
+    "create_flask_relay_handler": (".integrations.relay_flask", "create_flask_relay_handler"),
+    "instrument_fastapi": (".integrations.fastapi", "instrument_fastapi"),
+    "instrument_flask": (".integrations.flask", "instrument_flask"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _OPTIONAL_EXPORTS:
+        raise AttributeError(f"module 'debugbundle' has no attribute {name!r}")
+
+    module_name, attribute_name = _OPTIONAL_EXPORTS[name]
+    module = importlib.import_module(module_name, __name__)
+    return getattr(module, attribute_name)
+
+
+__all__ = [
+    "BrowserRelayAcceptedBatch",
+    "BrowserRelayHandler",
+    "BrowserRelayResponse",
+    "DebugBundleSdk",
+    "DebugBundleDjangoMiddleware",
+    "DebugBundleFastAPIMiddleware",
+    "begin_request",
+    "capture_async",
+    "capture_error",
+    "capture_exception",
+    "capture_exceptions",
+    "capture_log",
+    "capture_logging",
+    "capture_message",
+    "capture_request",
+    "create_django_relay_view",
+    "create_fastapi_relay_handler",
+    "create_flask_relay_handler",
+    "end_request",
+    "flush",
+    "init",
+    "instrument_fastapi",
+    "instrument_flask",
+    "probe",
+    "set_context",
+]

debugbundle/config.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_PROBES_POLL_INTERVAL_MS = 60_000
+
+
+@dataclass(frozen=True)
+class CapturePolicy:
+    preset: str
+    capture_logs: str
+    capture_request_events: str
+    capture_breadcrumbs: str
+    capture_probe_events: str
+
+
+@dataclass(frozen=True)
+class RemoteProbeDirective:
+    id: str
+    label_pattern: str
+    service: str
+    environment: str
+    expires_at: str
+
+
+@dataclass(frozen=True)
+class RemoteConfigSnapshot:
+    probes_enabled: bool
+    remote_probes_enabled: bool
+    directives: list[RemoteProbeDirective]
+    poll_interval_ms: int
+    capture_policy: CapturePolicy
+    trigger_token_key: str | None = None
+
+
+BALANCED_CAPTURE_POLICY = CapturePolicy(
+    preset="balanced",
+    capture_logs="warning",
+    capture_request_events="all",
+    capture_breadcrumbs="local_only",
+    capture_probe_events="standalone_when_activated",
+)
+
+MINIMAL_CAPTURE_POLICY = CapturePolicy(
+    preset="minimal",
+    capture_logs="warning",
+    capture_request_events="off",
+    capture_breadcrumbs="local_only",
+    capture_probe_events="buffer_only",
+)
+
+
+def parse_remote_config(payload: object, fallback_poll_interval_ms: int, now_ms: int) -> RemoteConfigSnapshot | None:
+    if not isinstance(payload, dict):
+        return None
+
+    probes_enabled = payload.get("probes_enabled") is True
+    remote_probes_enabled = payload.get("remote_probes_enabled") is True
+    poll_interval_candidate = payload.get("poll_interval_ms")
+    poll_interval_ms = (
+        int(poll_interval_candidate)
+        if isinstance(poll_interval_candidate, (int, float)) and int(poll_interval_candidate) > 0
+        else fallback_poll_interval_ms
+    )
+
+    directives: list[RemoteProbeDirective] = []
+    active_probes = payload.get("active_probes")
+    if isinstance(active_probes, list):
+        for directive in active_probes:
+            parsed = _parse_directive(directive)
+            if parsed is not None and _expires_at_ms(parsed.expires_at) > now_ms:
+                directives.append(parsed)
+
+    capture_policy = _parse_capture_policy(payload.get("capture_policy"))
+    if capture_policy is None:
+        return None
+
+    return RemoteConfigSnapshot(
+        probes_enabled=probes_enabled,
+        remote_probes_enabled=remote_probes_enabled,
+        directives=directives,
+        poll_interval_ms=poll_interval_ms if remote_probes_enabled else DEFAULT_PROBES_POLL_INTERVAL_MS,
+        capture_policy=capture_policy,
+        trigger_token_key=_as_non_empty_string(payload.get("trigger_token_key")),
+    )
+
+
+def find_matching_remote_probe_directives(
+    directives: list[RemoteProbeDirective],
+    label: str,
+    service: str,
+    environment: str,
+    now_ms: int,
+) -> list[RemoteProbeDirective]:
+    matches: list[RemoteProbeDirective] = []
+    for directive in directives:
+        if _expires_at_ms(directive.expires_at) <= now_ms:
+            continue
+        if directive.service != "*" and directive.service != service:
+            continue
+        if directive.environment != "*" and directive.environment != environment:
+            continue
+        if _matches_label_pattern(directive.label_pattern, label):
+            matches.append(directive)
+    return matches
+
+
+def _parse_capture_policy(payload: object) -> CapturePolicy | None:
+    if payload is None:
+        return BALANCED_CAPTURE_POLICY
+    if not isinstance(payload, dict):
+        return None
+
+    preset = _as_non_empty_string(payload.get("preset")) or BALANCED_CAPTURE_POLICY.preset
+    capture_logs = _as_non_empty_string(payload.get("capture_logs"))
+    capture_request_events = _as_non_empty_string(payload.get("capture_request_events"))
+    capture_breadcrumbs = _as_non_empty_string(payload.get("capture_breadcrumbs"))
+    capture_probe_events = _as_non_empty_string(payload.get("capture_probe_events"))
+
+    if capture_logs not in {"off", "error", "warning", "info"}:
+        return None
+    if capture_request_events not in {"off", "failures_only", "filtered", "all"}:
+        return None
+    if capture_breadcrumbs not in {"local_only", "exception_only", "standalone"}:
+        return None
+    if capture_probe_events not in {"buffer_only", "standalone_when_activated"}:
+        return None
+
+    return CapturePolicy(
+        preset=preset,
+        capture_logs=capture_logs,
+        capture_request_events=capture_request_events,
+        capture_breadcrumbs=capture_breadcrumbs,
+        capture_probe_events=capture_probe_events,
+    )
+
+
+def _parse_directive(payload: object) -> RemoteProbeDirective | None:
+    if not isinstance(payload, dict):
+        return None
+
+    directive_id = _as_non_empty_string(payload.get("id"))
+    label_pattern = _as_non_empty_string(payload.get("label_pattern"))
+    service = _as_non_empty_string(payload.get("service"))
+    environment = _as_non_empty_string(payload.get("environment"))
+    expires_at = _as_non_empty_string(payload.get("expires_at"))
+
+    if directive_id is None:
+        return None
+    if label_pattern is None:
+        return None
+    if service is None:
+        return None
+    if environment is None:
+        return None
+    if expires_at is None:
+        return None
+    if _expires_at_ms(expires_at) == 0:
+        return None
+
+    return RemoteProbeDirective(
+        id=directive_id,
+        label_pattern=label_pattern,
+        service=service,
+        environment=environment,
+        expires_at=expires_at,
+    )
+
+
+def _matches_label_pattern(pattern: str, label: str) -> bool:
+    if pattern == "*":
+        return True
+    if pattern.endswith(".*"):
+        prefix = pattern[:-2]
+        return label == prefix or label.startswith(f"{prefix}.")
+    return pattern == label
+
+
+def _expires_at_ms(value: str) -> int:
+    from datetime import datetime
+
+    try:
+        if value.endswith("Z"):
+            value = value[:-1] + "+00:00"
+        return int(datetime.fromisoformat(value).timestamp() * 1000)
+    except ValueError:
+        return 0
+
+
+def _as_non_empty_string(value: Any) -> str | None:
+    return value if isinstance(value, str) and len(value) > 0 else None