closeyourit 0.1.0__py3-none-any.whl

closeyourit/__init__.py

@@ -0,0 +1,61 @@
+"""Public package for the CloseYourIt Python SDK."""
+
+from closeyourit._version import __version__
+from closeyourit.asgi import ASGIMiddleware
+from closeyourit.client import Client, EventSink
+from closeyourit.configuration import Configuration
+from closeyourit.django import DjangoMiddleware
+from closeyourit.events import EventBuilder
+from closeyourit.flask import FlaskIntegration
+from closeyourit.hooks import CloseYourItHandler, ErrorHooks
+from closeyourit.integrations import (
+    CeleryIntegration,
+    HttpTarget,
+    HttpxInstrumentation,
+    RequestsInstrumentation,
+    SQLAlchemyInstrumentation,
+    instrument_httpx,
+    instrument_requests,
+    instrument_sqlalchemy,
+    normalize_http_target,
+)
+from closeyourit.scope import Scope, ScopeSnapshot, current_scope, reset_scope, with_scope
+from closeyourit.scrubber import FILTERED, Scrubber
+from closeyourit.sql import sql_fingerprint
+from closeyourit.transport import HttpResponse, Transport, TransportStats, UrllibHttpRequester
+from closeyourit.wsgi import WSGIMiddleware
+
+__all__ = [
+    "FILTERED",
+    "ASGIMiddleware",
+    "CeleryIntegration",
+    "Client",
+    "CloseYourItHandler",
+    "Configuration",
+    "DjangoMiddleware",
+    "ErrorHooks",
+    "EventBuilder",
+    "EventSink",
+    "FlaskIntegration",
+    "HttpResponse",
+    "HttpTarget",
+    "HttpxInstrumentation",
+    "RequestsInstrumentation",
+    "SQLAlchemyInstrumentation",
+    "Scope",
+    "ScopeSnapshot",
+    "Scrubber",
+    "Transport",
+    "TransportStats",
+    "UrllibHttpRequester",
+    "WSGIMiddleware",
+    "__version__",
+    "current_scope",
+    "instrument_httpx",
+    "instrument_requests",
+    "instrument_sqlalchemy",
+    "normalize_http_target",
+    "reset_scope",
+    "sql_fingerprint",
+    "with_scope",
+]

closeyourit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

closeyourit/asgi.py

@@ -0,0 +1,73 @@
+"""Dependency-free ASGI 3 middleware."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable
+
+from closeyourit.client import Client
+from closeyourit.scope import with_scope
+from closeyourit.web import Monotonic, RequestLifecycle, asgi_request, route_from_asgi
+
+Message = dict[str, object]
+ASGIApp = Callable[..., Awaitable[None]]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+
+class ASGIMiddleware:
+    """Capture one HTTP connection scope while forwarding receive/send unchanged."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        client: Client,
+        *,
+        monotonic: Monotonic = time.monotonic,
+    ) -> None:
+        self.app = app
+        self.client = client
+        self.monotonic = monotonic
+
+    async def __call__(
+        self,
+        scope: dict[str, object],
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request, trace_id = asgi_request(scope, self.client.configuration.request_header_allowlist)
+        lifecycle = RequestLifecycle(
+            self.client,
+            request,
+            trace_id,
+            route_resolver=lambda: route_from_asgi(scope),
+            monotonic=self.monotonic,
+        )
+        send_error: Exception | None = None
+
+        async def observed_send(message: Message) -> None:
+            nonlocal send_error
+            if message.get("type") == "http.response.start":
+                lifecycle.set_status(message.get("status"))
+            try:
+                await send(message)
+            except Exception as error:
+                send_error = error
+                raise
+
+        with with_scope():
+            lifecycle.begin()
+            try:
+                await self.app(scope, receive, observed_send)
+            except Exception as error:
+                if error is send_error:
+                    lifecycle.finish()
+                else:
+                    lifecycle.finish(error)
+                raise
+            else:
+                lifecycle.finish()

closeyourit/client.py

@@ -0,0 +1,240 @@
+"""Public capture facade independent from the concrete asynchronous transport."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+from collections.abc import Callable, Mapping
+from typing import Literal, Protocol, TypeVar, runtime_checkable
+
+from closeyourit.configuration import Configuration
+from closeyourit.events import EventBuilder
+from closeyourit.models import EventPayload
+from closeyourit.scope import current_scope
+
+Channel = Literal["events", "logs", "metrics"]
+T = TypeVar("T")
+
+
+class EventSink(Protocol):
+    def enqueue(self, channel: Channel, payload: EventPayload) -> bool: ...
+
+
+@runtime_checkable
+class FlushableSink(Protocol):
+    def flush(self, timeout: float | None = None) -> bool: ...
+
+
+@runtime_checkable
+class CloseableSink(Protocol):
+    def close(self, timeout: float | None = None) -> bool: ...
+
+
+class NullSink:
+    def enqueue(self, channel: Channel, payload: EventPayload) -> bool:
+        del channel, payload
+        return False
+
+
+class Client:
+    """Build, scrub and hand payloads to a replaceable non-blocking sink."""
+
+    def __init__(
+        self,
+        configuration: Configuration | None = None,
+        *,
+        sink: EventSink | None = None,
+        random_value: Callable[[], float] = random.random,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.configuration = configuration or Configuration()
+        if sink is None and self.configuration.enabled:
+            from closeyourit.transport import Transport
+
+            sink = Transport(self.configuration)
+        self.sink = sink or NullSink()
+        self.random_value = random_value
+        self.monotonic = monotonic
+        self.builder = EventBuilder(self.configuration)
+
+    def capture_exception(
+        self,
+        error: BaseException,
+        *,
+        handled: bool = False,
+        level: str = "error",
+        contexts: Mapping[str, object] | None = None,
+    ) -> str | None:
+        if not self._sampled(self.configuration.sample_rate):
+            return None
+        return self._submit(
+            "events",
+            self.builder.exception(error, handled=handled, level=level, contexts=contexts),
+        )
+
+    def capture_message(self, message: object, *, level: str = "info") -> str | None:
+        if not self._sampled(self.configuration.sample_rate):
+            return None
+        return self._submit("events", self.builder.message(message, level=level))
+
+    def log(
+        self,
+        message: object,
+        *,
+        level: str = "info",
+        logger: str | None = None,
+        **attributes: object,
+    ) -> str | None:
+        if not self._sampled(self.configuration.logs_sample_rate):
+            return None
+        return self._submit(
+            "logs",
+            self.builder.log(message, level=level, logger=logger, attributes=attributes),
+        )
+
+    def add_breadcrumb(
+        self,
+        *,
+        message: str | None = None,
+        category: str | None = None,
+        type: str = "default",
+        level: str = "info",
+        data: Mapping[str, object] | None = None,
+    ) -> None:
+        if not self.configuration.breadcrumbs_enabled:
+            return
+        breadcrumb: EventPayload = {
+            "timestamp": self.builder.timestamp(),
+            "type": type,
+            "level": level,
+        }
+        if message is not None:
+            breadcrumb["message"] = message
+        if category is not None:
+            breadcrumb["category"] = category
+        if data:
+            breadcrumb["data"] = dict(data)
+        current_scope().add_breadcrumb(
+            breadcrumb, max_breadcrumbs=self.configuration.max_breadcrumbs
+        )
+
+    def measure(self, label: str, operation: Callable[[], T]) -> T:
+        label = label.strip()
+        if not label:
+            raise ValueError("measurement label must not be blank")
+        started_at = self.monotonic()
+        try:
+            return operation()
+        finally:
+            duration_ms = (self.monotonic() - started_at) * 1000.0
+            if duration_ms >= self.configuration.slow_method_threshold_ms:
+                self.capture_duration(label, duration_ms)
+
+    def capture_duration(
+        self,
+        label: str,
+        duration_ms: float,
+        *,
+        contexts: Mapping[str, object] | None = None,
+    ) -> str | None:
+        """Capture a finite duration enriched with release and scrubbed integration context."""
+        try:
+            normalized_duration = float(duration_ms)
+        except (TypeError, ValueError, OverflowError):
+            return None
+        if not math.isfinite(normalized_duration):
+            return None
+        payload = self.builder.slow_method(label, max(0.0, normalized_duration))
+        if self.configuration.release is not None:
+            payload["release"] = self.configuration.release
+        if contexts:
+            payload["contexts"] = self.builder.scrubber.scrub(dict(contexts))
+        return self._submit("metrics", payload)
+
+    def capture_slow_request(
+        self,
+        *,
+        route: str,
+        path: str,
+        url: str,
+        duration_ms: float,
+    ) -> str | None:
+        return self._submit(
+            "metrics",
+            self.builder.slow_request(
+                route=route,
+                path=path,
+                url=url,
+                duration_ms=duration_ms,
+            ),
+        )
+
+    def capture_slow_query(
+        self,
+        sql: str,
+        duration_ms: float,
+        *,
+        db_system: str | None = None,
+        source: str | None = None,
+    ) -> str | None:
+        return self._submit(
+            "metrics",
+            self.builder.slow_query(sql, duration_ms, db_system=db_system, source=source),
+        )
+
+    def capture_performance_issue(
+        self,
+        subtype: str,
+        *,
+        duration_ms: float | None = None,
+        sql: str | None = None,
+        source: str | None = None,
+        route: str | None = None,
+        http_host: str | None = None,
+        http_url: str | None = None,
+        query_count: int | None = None,
+        total_query_time_ms: float | None = None,
+    ) -> str | None:
+        return self._submit(
+            "metrics",
+            self.builder.performance_issue(
+                subtype,
+                duration_ms=duration_ms,
+                sql=sql,
+                source=source,
+                route=route,
+                http_host=http_host,
+                http_url=http_url,
+                query_count=query_count,
+                total_query_time_ms=total_query_time_ms,
+            ),
+        )
+
+    def flush(self, timeout: float | None = None) -> bool:
+        """Wait for an asynchronous sink, or succeed immediately for a synchronous sink."""
+        if isinstance(self.sink, FlushableSink):
+            return self.sink.flush(timeout)
+        return True
+
+    def close(self, timeout: float | None = None) -> bool:
+        """Close a managed sink idempotently."""
+        if isinstance(self.sink, CloseableSink):
+            return self.sink.close(timeout)
+        return True
+
+    def _sampled(self, rate: float) -> bool:
+        return (
+            self.configuration.enabled
+            and rate > 0.0
+            and (rate >= 1.0 or self.random_value() < rate)
+        )
+
+    def _submit(self, channel: Channel, payload: EventPayload) -> str | None:
+        if not self.configuration.enabled:
+            return None
+        prepared = self.configuration.apply_before_send(payload)
+        if prepared is None or not self.sink.enqueue(channel, prepared):
+            return None
+        identifier = prepared.get("event_id", prepared.get("sample_id"))
+        return str(identifier) if identifier is not None else None

closeyourit/configuration.py

@@ -0,0 +1,181 @@
+"""Immutable, fail-safe configuration for the CloseYourIt client."""
+
+from __future__ import annotations
+
+import os
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Literal, TypeAlias
+from urllib.parse import urlsplit
+from uuid import UUID
+
+from closeyourit.models import BeforeSend, EventPayload, FilterParameter
+
+DisabledReason: TypeAlias = Literal[
+    "missing_endpoint_url",
+    "missing_token",
+    "missing_project_id",
+    "invalid_endpoint_url",
+    "insecure_endpoint_in_production",
+    "invalid_token",
+    "invalid_project_id",
+]
+
+
+def _optional_environment(name: str) -> str | None:
+    return os.environ.get(name)
+
+
+def _environment() -> str:
+    return os.environ.get("CLOSEYOURIT_ENVIRONMENT", "development")
+
+
+def _clean_optional(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    return cleaned or None
+
+
+@dataclass(frozen=True, slots=True)
+class Configuration:
+    """Validated settings; invalid or incomplete values make the SDK a no-op."""
+
+    endpoint_url: str | None = field(
+        default_factory=lambda: _optional_environment("CLOSEYOURIT_ENDPOINT_URL")
+    )
+    token: str | None = field(default_factory=lambda: _optional_environment("CLOSEYOURIT_TOKEN"))
+    project_id: str | None = field(
+        default_factory=lambda: _optional_environment("CLOSEYOURIT_PROJECT_ID")
+    )
+    environment: str = field(default_factory=_environment)
+    release: str | None = field(
+        default_factory=lambda: _optional_environment("CLOSEYOURIT_RELEASE")
+    )
+    send_pii: bool = False
+    filter_parameters: tuple[FilterParameter, ...] = ()
+    before_send: BeforeSend | None = None
+    sample_rate: float = 1.0
+    logs_sample_rate: float = 1.0
+    breadcrumbs_enabled: bool = True
+    max_breadcrumbs: int = 100
+    slow_method_threshold_ms: float = 500.0
+    slow_request_threshold_ms: float = 1000.0
+    request_header_allowlist: tuple[str, ...] = (
+        "Accept",
+        "Content-Type",
+        "User-Agent",
+    )
+    slow_query_threshold_ms: float = 100.0
+    slow_external_threshold_ms: float = 1_000.0
+    repeated_http_threshold: int = 5
+    repeated_http_window_ms: float = 5_000.0
+    n_plus_one_threshold: int = 10
+    query_count_threshold: int = 100
+    http_capture_hosts: tuple[str, ...] = ()
+    trace_propagation_enabled: bool = False
+    trace_propagation_hosts: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        endpoint = _clean_optional(self.endpoint_url)
+        object.__setattr__(self, "endpoint_url", endpoint.rstrip("/") if endpoint else None)
+        object.__setattr__(self, "token", _clean_optional(self.token))
+        object.__setattr__(self, "project_id", _clean_optional(self.project_id))
+        environment = self.environment.strip().casefold() or "development"
+        object.__setattr__(self, "environment", environment)
+        object.__setattr__(self, "release", _clean_optional(self.release))
+        object.__setattr__(self, "filter_parameters", tuple(self.filter_parameters))
+        object.__setattr__(self, "sample_rate", min(1.0, max(0.0, float(self.sample_rate))))
+        object.__setattr__(
+            self, "logs_sample_rate", min(1.0, max(0.0, float(self.logs_sample_rate)))
+        )
+        object.__setattr__(self, "max_breadcrumbs", max(0, int(self.max_breadcrumbs)))
+        object.__setattr__(
+            self, "slow_method_threshold_ms", max(0.0, float(self.slow_method_threshold_ms))
+        )
+        object.__setattr__(
+            self, "slow_request_threshold_ms", max(0.0, float(self.slow_request_threshold_ms))
+        )
+        object.__setattr__(
+            self,
+            "request_header_allowlist",
+            tuple(
+                dict.fromkeys(
+                    name.strip() for name in self.request_header_allowlist if name.strip()
+                )
+            ),
+        )
+        object.__setattr__(
+            self, "slow_query_threshold_ms", max(0.0, float(self.slow_query_threshold_ms))
+        )
+        object.__setattr__(
+            self,
+            "slow_external_threshold_ms",
+            max(0.0, float(self.slow_external_threshold_ms)),
+        )
+        object.__setattr__(
+            self, "repeated_http_threshold", max(1, int(self.repeated_http_threshold))
+        )
+        object.__setattr__(
+            self, "repeated_http_window_ms", max(0.0, float(self.repeated_http_window_ms))
+        )
+        object.__setattr__(self, "n_plus_one_threshold", max(0, int(self.n_plus_one_threshold)))
+        object.__setattr__(self, "query_count_threshold", max(0, int(self.query_count_threshold)))
+        object.__setattr__(
+            self,
+            "http_capture_hosts",
+            tuple(host.strip().casefold() for host in self.http_capture_hosts if host.strip()),
+        )
+        object.__setattr__(
+            self,
+            "trace_propagation_hosts",
+            tuple(host.strip().casefold() for host in self.trace_propagation_hosts if host.strip()),
+        )
+
+    @property
+    def production(self) -> bool:
+        return self.environment == "production"
+
+    @property
+    def enabled(self) -> bool:
+        return self.disabled_reason is None
+
+    @property
+    def disabled_reason(self) -> DisabledReason | None:
+        if self.endpoint_url is None:
+            return "missing_endpoint_url"
+        if self.token is None:
+            return "missing_token"
+        if self.project_id is None:
+            return "missing_project_id"
+
+        endpoint = urlsplit(self.endpoint_url)
+        if (
+            endpoint.scheme not in {"http", "https"}
+            or endpoint.hostname is None
+            or endpoint.username is not None
+            or endpoint.password is not None
+        ):
+            return "invalid_endpoint_url"
+        if self.production and endpoint.scheme != "https":
+            return "insecure_endpoint_in_production"
+        if not self.token.startswith("cyi_"):
+            return "invalid_token"
+        try:
+            if str(UUID(self.project_id)) != self.project_id.casefold():
+                return "invalid_project_id"
+        except ValueError:
+            return "invalid_project_id"
+
+        return None
+
+    def apply_before_send(self, event: EventPayload) -> EventPayload | None:
+        """Run the consumer hook on a copy; callback failures safely drop the event."""
+        try:
+            payload = deepcopy(event)
+            if self.before_send is None:
+                return payload
+            result = self.before_send(payload)
+            return deepcopy(result) if isinstance(result, dict) else None
+        except Exception:
+            return None