moolabs 0.3.0__py3-none-any.whl

moolabs/_dx_attribution_db_time.py

@@ -0,0 +1,2126 @@
+"""Redacted SQLAlchemy DB-time attribution instrumentation."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+import heapq
+import hashlib
+from importlib import metadata
+import json
+import math
+import os
+import queue
+import re
+import socket
+import sys
+import threading
+import time
+from typing import Any, Literal
+import uuid
+import weakref
+
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
+from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+from opentelemetry.trace import Link, SpanKind, TraceFlags
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from ._dx_attribution_context import (
+    _normalized_dimensions,
+    get_attribution_context,
+)
+
+
+_SPAN_NAME = "moolabs.db_time.query"
+_SCHEMA_VERSION = 1
+_COMMENT_RE = re.compile(
+    r"^/\*moolabs_db_time:v1;ob=([0-9a-f]{32})\*/$",
+    re.ASCII,
+)
+_POOL_KEY_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,47}$", re.ASCII)
+_UNATTRIBUTED_IDENTITY_PAIR = ("__unattributed__", "__unattributed__")
+_TRANSACTION_ID_KEY = "moolabs.db_time.v1.transaction_id"
+_STATEMENT_STATE_KEY = "_moolabs_db_time_v1_state"
+
+_ALLOWED_SPAN_ATTRIBUTES = (
+    "db.system",
+    "moolabs.db_time.schema_version",
+    "moolabs.db_time.sql_comment",
+    "moolabs.db_time.observation_id",
+    "moolabs.db_time.service",
+    "moolabs.db_time.pool_key",
+)
+
+
+def _as_utc(value: datetime) -> datetime:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError("DB-time timestamps must be timezone-aware")
+    return value.astimezone(timezone.utc)
+
+
+def _floor_second(value: datetime) -> datetime:
+    return _as_utc(value).replace(microsecond=0)
+
+
+def _next_midnight(value: datetime) -> datetime:
+    utc = _as_utc(value)
+    return (utc + timedelta(days=1)).replace(
+        hour=0,
+        minute=0,
+        second=0,
+        microsecond=0,
+    )
+
+
+def _window_boundary(window_start: datetime, interval_sec: float) -> datetime:
+    return min(
+        window_start + timedelta(seconds=interval_sec),
+        _next_midnight(window_start),
+    )
+
+
+def _format_utc(value: datetime) -> str:
+    utc = _as_utc(value)
+    timespec = "seconds" if utc.microsecond == 0 else "microseconds"
+    return utc.isoformat(timespec=timespec).replace("+00:00", "Z")
+
+
+@dataclass(frozen=True, slots=True)
+class _PendingDbObservation:
+    observation_id: uuid.UUID
+    transaction_id: uuid.UUID
+    request_id_hash: str | None
+    thread_id_hash: str | None
+    customer_external_key: str
+    feature_key: str
+    started_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class _CompletedDbObservation:
+    pending: _PendingDbObservation
+    trace_id: str
+    span_id: str
+    linked_trace_id: str | None
+    duration_ns: int
+    outcome: Literal["ok", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class _InstallConfig:
+    service: str
+    pool_key: str
+    sample_rate: float
+    tracer_provider_identity: int
+    flush_callback_identity: tuple[int | None, int] | None
+
+
+@dataclass(slots=True)
+class _StatementState:
+    span: Any
+    observation_key: str | None
+    sampled: bool
+    statement_local_transaction: bool
+    _ended: bool = False
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def mark_ended(self) -> bool:
+        with self._lock:
+            if self._ended:
+                return False
+            self._ended = True
+            return True
+
+
+class _DbTimeFlushOutcome(str, Enum):
+    DELIVERED = "delivered"
+    TERMINAL_DROP = "terminal_drop"
+    RETRY_EXHAUSTED = "retry_exhausted"
+
+
+@dataclass(frozen=True, slots=True)
+class _FrozenDbTimeBatch:
+    body: bytes
+    batch_id: uuid.UUID
+    batch_seq: int
+    pod_instance_id: uuid.UUID
+    service: str
+    pool_key: str
+    pod_id: str
+    window_start: str
+    attempted_count: int
+    sampled_count: int
+    dropped_count: int
+    observations: tuple[_CompletedDbObservation, ...]
+
+
+DbTimeFlushCallback = Callable[[_FrozenDbTimeBatch], _DbTimeFlushOutcome]
+
+
+@dataclass(frozen=True, slots=True)
+class _StartRecord:
+    started_at: datetime
+    pending: _PendingDbObservation | None
+
+
+@dataclass(frozen=True, slots=True)
+class _EndRecord:
+    observation_id: uuid.UUID
+    trace_id: str
+    span_id: str
+    linked_trace_id: str | None
+    duration_ns: int
+    outcome: Literal["ok", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class _DropRecord:
+    observation_id: uuid.UUID
+
+
+@dataclass(frozen=True, slots=True)
+class _FlushRecord:
+    force: bool
+    done: threading.Event
+
+
+@dataclass(frozen=True, slots=True)
+class _SyncRecord:
+    done: threading.Event
+
+
+@dataclass(frozen=True, slots=True)
+class _CloseRecord:
+    deadline: float
+    done: threading.Event
+
+
+@dataclass(slots=True)
+class _FlushBarrier:
+    window_keys: set[int]
+    done: threading.Event
+
+
+@dataclass(slots=True)
+class _OverflowBucket:
+    started_at: datetime
+    attempted_count: int = 0
+    sampled_count: int = 0
+
+
+@dataclass(slots=True)
+class _OverflowRecord:
+    max_buckets: int
+    buckets: dict[datetime, _OverflowBucket] = field(default_factory=dict)
+
+    def add(self, record: _StartRecord) -> bool:
+        started_at = _floor_second(record.started_at)
+        bucket = self.buckets.get(started_at)
+        if bucket is None:
+            if len(self.buckets) >= self.max_buckets:
+                return False
+            bucket = _OverflowBucket(started_at=started_at)
+            self.buckets[started_at] = bucket
+        bucket.attempted_count += 1
+        if record.pending is not None:
+            bucket.sampled_count += 1
+        return True
+
+    def snapshot(self) -> tuple[_OverflowBucket, ...]:
+        return tuple(self.buckets[key] for key in sorted(self.buckets))
+
+
+class _BoundedDbTimeInbox:
+    """Bound data records while reserving every admitted sampled completion."""
+
+    def __init__(self, capacity: int, *, overflow_bucket_capacity: int) -> None:
+        self._capacity = capacity
+        self._overflow_bucket_capacity = overflow_bucket_capacity
+        self._condition = threading.Condition()
+        self._items: deque[object] = deque()
+        self._data_count = 0
+        self._admitted_ids: set[uuid.UUID] = set()
+        self._active_overflow: _OverflowRecord | None = None
+        self._ineligible_attempted_count = 0
+        self._ineligible_sampled_count = 0
+
+    def put(self, record: object) -> bool:
+        with self._condition:
+            if isinstance(record, _StartRecord):
+                return self._put_start(record)
+            if isinstance(record, (_EndRecord, _DropRecord)):
+                return self._put_terminal(record)
+            self._active_overflow = None
+            self._items.append(record)
+            self._condition.notify()
+            return True
+
+    def _put_start(self, record: _StartRecord) -> bool:
+        pending = record.pending
+        observation_id = pending.observation_id if pending is not None else None
+        required = 2 if observation_id is not None else 1
+        used = self._data_count + len(self._admitted_ids)
+        if (
+            used + required <= self._capacity
+            and observation_id not in self._admitted_ids
+        ):
+            self._active_overflow = None
+            if observation_id is not None:
+                self._admitted_ids.add(observation_id)
+            self._items.append(record)
+            self._data_count += 1
+            self._condition.notify()
+            return True
+
+        overflow = self._active_overflow
+        if overflow is None:
+            overflow = _OverflowRecord(max_buckets=self._overflow_bucket_capacity)
+            self._active_overflow = overflow
+            self._items.append(overflow)
+            self._condition.notify()
+        if not overflow.add(record):
+            self._ineligible_attempted_count += 1
+            if record.pending is not None:
+                self._ineligible_sampled_count += 1
+        return False
+
+    def _put_terminal(self, record: _EndRecord | _DropRecord) -> bool:
+        observation_id = record.observation_id
+        if observation_id not in self._admitted_ids:
+            return False
+        self._admitted_ids.remove(observation_id)
+        self._items.append(record)
+        self._data_count += 1
+        self._condition.notify()
+        return True
+
+    def get(self, timeout: float | None = None) -> object:
+        with self._condition:
+            deadline = None if timeout is None else time.monotonic() + timeout
+            while not self._items:
+                if deadline is None:
+                    self._condition.wait()
+                    continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise queue.Empty
+                self._condition.wait(remaining)
+
+            record = self._items.popleft()
+            if isinstance(record, (_StartRecord, _EndRecord, _DropRecord)):
+                self._data_count -= 1
+            if record is self._active_overflow:
+                self._active_overflow = None
+            return record
+
+    def get_nowait(self) -> object:
+        return self.get(timeout=0.0)
+
+    def discard_admitted(self, observation_id: uuid.UUID) -> None:
+        with self._condition:
+            self._admitted_ids.discard(observation_id)
+
+    def qsize(self) -> int:
+        with self._condition:
+            return self._data_count + len(self._admitted_ids)
+
+    def admitted_count(self) -> int:
+        with self._condition:
+            return len(self._admitted_ids)
+
+    def consume_ineligible_overflow(self) -> tuple[int, int]:
+        with self._condition:
+            counts = (
+                self._ineligible_attempted_count,
+                self._ineligible_sampled_count,
+            )
+            self._ineligible_attempted_count = 0
+            self._ineligible_sampled_count = 0
+            return counts
+
+
+@dataclass(slots=True)
+class _MutableDbWindow:
+    key: int
+    window_start: datetime
+    boundary_at: datetime
+    attempted_count: int = 0
+    sampled_count: int = 0
+    dropped_count: int = 0
+    inflight: set[uuid.UUID] = field(default_factory=set)
+    observations: dict[uuid.UUID, _CompletedDbObservation] = field(default_factory=dict)
+    sealed_at: datetime | None = None
+
+
+class _DbTimeWindowOwner:
+    """Single-thread owner for DB-time windows, retention, freeze, and delivery."""
+
+    def __init__(
+        self,
+        *,
+        service: str,
+        pool_key: str,
+        pod_id: str,
+        sample_rate: float,
+        queue_capacity: int,
+        overflow_bucket_capacity: int,
+        batch_size: int,
+        flush_interval_sec: float,
+        flush_callback: DbTimeFlushCallback | None,
+        logger: Callable[[str, dict[str, Any]], None] | None,
+        utc_now: Callable[[], datetime],
+        monotonic: Callable[[], float],
+    ) -> None:
+        self.service = service
+        self.pool_key = pool_key
+        self.pod_id = pod_id
+        self.sample_rate = sample_rate
+        self.pod_instance_id = uuid.uuid4()
+        self._queue_capacity = queue_capacity
+        self._batch_size = batch_size
+        self._flush_interval_sec = flush_interval_sec
+        self._flush_callback = flush_callback
+        self._logger = logger
+        self._utc_now = utc_now
+        self._monotonic = monotonic
+        self._records = _BoundedDbTimeInbox(
+            queue_capacity,
+            overflow_bucket_capacity=overflow_bucket_capacity,
+        )
+        self._state_lock = threading.RLock()
+        self._command_lock = threading.Lock()
+        self._windows: dict[int, _MutableDbWindow] = {}
+        self._open_window_key: int | None = None
+        self._next_window_key = 1
+        self._next_window_start_hint: datetime | None = None
+        self._pending: dict[
+            uuid.UUID,
+            tuple[_PendingDbObservation, int],
+        ] = {}
+        self._completed_heap: list[tuple[datetime, str, uuid.UUID, int]] = []
+        self._completed_locations: dict[uuid.UUID, int] = {}
+        self._batch_seq = 0
+        self._closing = False
+        self._close_done: threading.Event | None = None
+        self._flush_barriers: list[_FlushBarrier] = []
+        self._closed = False
+        self._stats = {
+            "attempted_count": 0,
+            "sampled_start_count": 0,
+            "completed_count": 0,
+            "pending_count": 0,
+            "dropped_count": 0,
+            "abandoned_inflight": 0,
+            "delivered_batches": 0,
+            "terminal_dropped_batches": 0,
+            "retry_exhausted_batches": 0,
+            "callback_failures": 0,
+            "overflow_ineligible_count": 0,
+            "overflow_ineligible_batches": 0,
+        }
+        self.thread = threading.Thread(
+            target=self._run,
+            name="moolabs-db-time-owner",
+            daemon=True,
+        )
+        self.thread.start()
+
+    def submit(self, record: object) -> None:
+        try:
+            self._records.put(record)
+        except Exception:
+            return
+
+    def flush(self, *, force: bool) -> None:
+        if threading.current_thread() is self.thread:
+            if force:
+                self._seal_open(self._utc_now())
+            else:
+                self._seal_due(self._utc_now())
+            self._deliver_ready_one()
+            return
+        with self._command_lock:
+            with self._state_lock:
+                if self._closing:
+                    return
+            done = threading.Event()
+            self.submit(_FlushRecord(force=force, done=done))
+            while self.thread.is_alive() and not done.wait(timeout=0.1):
+                continue
+
+    def stats(self) -> dict[str, int]:
+        if threading.current_thread() is not self.thread and self.thread.is_alive():
+            with self._command_lock:
+                with self._state_lock:
+                    closing = self._closing
+                if not closing:
+                    done = threading.Event()
+                    self.submit(_SyncRecord(done))
+                    while self.thread.is_alive() and not done.wait(timeout=0.1):
+                        continue
+        with self._state_lock:
+            return dict(self._stats)
+
+    def request_close(self, deadline: float) -> threading.Event:
+        if threading.current_thread() is self.thread:
+            return self._request_close(deadline)
+        with self._command_lock:
+            return self._request_close(deadline)
+
+    def _request_close(self, deadline: float) -> threading.Event:
+        with self._state_lock:
+            if self._close_done is not None:
+                return self._close_done
+            self._closing = True
+            done = threading.Event()
+            self._close_done = done
+        self.submit(_CloseRecord(deadline=deadline, done=done))
+        return done
+
+    def _run(self) -> None:
+        while True:
+            record: object | None = None
+            try:
+                timeout = self._wait_timeout()
+                record = self._records.get(timeout=timeout)
+            except queue.Empty:
+                pass
+            try:
+                close_record = self._drain_available(record)
+                if close_record is not None:
+                    try:
+                        self._finish_close(close_record)
+                    finally:
+                        return
+                self._sync_ineligible_overflow()
+                self._seal_due(self._utc_now())
+                self._deliver_ready_one()
+            except Exception:
+                if isinstance(record, (_FlushRecord, _SyncRecord)):
+                    record.done.set()
+
+    def _wait_timeout(self) -> float | None:
+        if self._ready_windows():
+            return 0.0
+        window = self._open_window()
+        if window is None:
+            return None
+        remaining = (window.boundary_at - self._utc_now()).total_seconds()
+        return max(0.0, min(remaining, self._flush_interval_sec))
+
+    def _process(self, record: object) -> None:
+        if isinstance(record, _StartRecord):
+            self._process_start(record)
+        elif isinstance(record, _OverflowRecord):
+            self._process_overflow(record)
+        elif isinstance(record, _EndRecord):
+            self._process_end(record)
+        elif isinstance(record, _DropRecord):
+            self._process_drop(record.observation_id, abandoned=False)
+        elif isinstance(record, _FlushRecord):
+            if record.force:
+                self._seal_open(self._utc_now())
+            else:
+                self._seal_due(self._utc_now())
+            ready_keys = {window.key for window in self._ready_windows()}
+            if ready_keys:
+                self._flush_barriers.append(
+                    _FlushBarrier(window_keys=ready_keys, done=record.done)
+                )
+            else:
+                record.done.set()
+        elif isinstance(record, _SyncRecord):
+            record.done.set()
+
+    def _drain_available(self, first_record: object | None) -> _CloseRecord | None:
+        record = first_record
+        limit = self._queue_capacity + 8
+        for _ in range(limit):
+            if record is None:
+                try:
+                    record = self._records.get_nowait()
+                except queue.Empty:
+                    return None
+            if isinstance(record, _CloseRecord):
+                return record
+            self._process(record)
+            record = None
+        return None
+
+    def _sync_ineligible_overflow(self) -> None:
+        attempted_count, sampled_count = self._records.consume_ineligible_overflow()
+        if attempted_count == 0:
+            return
+        self._increment("attempted_count", attempted_count)
+        self._increment("sampled_start_count", sampled_count)
+        self._increment("dropped_count", sampled_count)
+        self._increment("overflow_ineligible_count", attempted_count)
+        self._increment("overflow_ineligible_batches")
+        # Consume one wire identity so a later accepted batch exposes the loss.
+        self._batch_seq += 1
+        self._safe_log(
+            "moolabs.attribution.db_time.overflow_ineligible",
+            {
+                "attempted_count": attempted_count,
+                "sampled_count": sampled_count,
+                "missing_batch_seq": self._batch_seq,
+            },
+        )
+
+    def _process_overflow(self, record: _OverflowRecord) -> None:
+        for bucket in record.snapshot():
+            self._process_overflow_bucket(bucket)
+
+    def _process_overflow_bucket(self, bucket: _OverflowBucket) -> None:
+        started_at = _as_utc(bucket.started_at)
+        unsampled_count = bucket.attempted_count - bucket.sampled_count
+        if unsampled_count:
+            self._advance_for_start(started_at)
+            window = self._open_window()
+            if window is None:
+                window = self._new_window(started_at)
+            window.attempted_count += unsampled_count
+            self._increment("attempted_count", unsampled_count)
+
+        sampled_remaining = bucket.sampled_count
+        while sampled_remaining:
+            self._advance_for_start(started_at)
+            window = self._open_window()
+            if window is None:
+                window = self._new_window(started_at)
+            sampled_capacity = self._batch_size - window.sampled_count
+            sampled_count = min(sampled_remaining, sampled_capacity)
+            window.attempted_count += sampled_count
+            window.sampled_count += sampled_count
+            window.dropped_count += sampled_count
+            self._increment("attempted_count", sampled_count)
+            self._increment("sampled_start_count", sampled_count)
+            self._increment("dropped_count", sampled_count)
+            sampled_remaining -= sampled_count
+            if window.sampled_count >= self._batch_size:
+                self._seal_window(window, started_at)
+                self._open_window_key = None
+                self._next_window_start_hint = None
+
+    def _process_start(self, record: _StartRecord) -> None:
+        started_at = _as_utc(record.started_at)
+        self._advance_for_start(started_at)
+        window = self._open_window()
+        if window is None:
+            window = self._new_window(started_at)
+        window.attempted_count += 1
+        self._increment("attempted_count")
+        pending = record.pending
+        if pending is None:
+            return
+        observation_id = pending.observation_id
+        if (
+            observation_id in self._pending
+            or observation_id in self._completed_locations
+        ):
+            window.dropped_count += 1
+            self._increment("dropped_count")
+            return
+        window.sampled_count += 1
+        window.inflight.add(observation_id)
+        self._pending[observation_id] = (pending, window.key)
+        self._increment("sampled_start_count")
+        self._set_pending_count()
+        if window.sampled_count >= self._batch_size:
+            self._seal_window(window, started_at)
+            self._open_window_key = None
+            self._next_window_start_hint = None
+
+    def _process_end(self, record: _EndRecord) -> None:
+        pending_entry = self._pending.pop(record.observation_id, None)
+        if pending_entry is None:
+            return
+        pending, window_key = pending_entry
+        window = self._windows.get(window_key)
+        if window is None:
+            self._set_pending_count()
+            return
+        window.inflight.discard(record.observation_id)
+        if (
+            type(record.duration_ns) is not int
+            or not 0 <= record.duration_ns <= 86_400_000_000_000
+        ):
+            window.dropped_count += 1
+            self._increment("dropped_count")
+            self._set_pending_count()
+            return
+        completed = _CompletedDbObservation(
+            pending=pending,
+            trace_id=record.trace_id,
+            span_id=record.span_id,
+            linked_trace_id=record.linked_trace_id,
+            duration_ns=record.duration_ns,
+            outcome=record.outcome,
+        )
+        window.observations[record.observation_id] = completed
+        self._completed_locations[record.observation_id] = window_key
+        heapq.heappush(
+            self._completed_heap,
+            (
+                pending.started_at,
+                pending.observation_id.hex,
+                pending.observation_id,
+                window_key,
+            ),
+        )
+        self._increment("completed_count")
+        self._set_pending_count()
+        self._evict_completed_overflow()
+
+    def _process_drop(self, observation_id: uuid.UUID, *, abandoned: bool) -> None:
+        self._records.discard_admitted(observation_id)
+        pending_entry = self._pending.pop(observation_id, None)
+        if pending_entry is None:
+            return
+        _pending, window_key = pending_entry
+        window = self._windows.get(window_key)
+        if window is not None:
+            window.inflight.discard(observation_id)
+            window.dropped_count += 1
+        self._increment("dropped_count")
+        if abandoned:
+            self._increment("abandoned_inflight")
+        self._set_pending_count()
+
+    def _evict_completed_overflow(self) -> None:
+        while len(self._completed_locations) > self._queue_capacity:
+            if not self._completed_heap:
+                return
+            _started_at, _hex, observation_id, window_key = heapq.heappop(
+                self._completed_heap
+            )
+            current_window_key = self._completed_locations.get(observation_id)
+            if current_window_key != window_key:
+                continue
+            del self._completed_locations[observation_id]
+            window = self._windows.get(window_key)
+            if window is None or window.observations.pop(observation_id, None) is None:
+                continue
+            window.dropped_count += 1
+            self._increment("dropped_count")
+
+    def _advance_for_start(self, started_at: datetime) -> None:
+        window = self._open_window()
+        if window is not None and started_at < window.window_start:
+            self._seal_window(window, window.boundary_at)
+            self._open_window_key = None
+            self._next_window_start_hint = None
+            window = None
+        if window is not None and started_at >= window.boundary_at:
+            self._seal_window(window, window.boundary_at)
+            self._open_window_key = None
+            self._next_window_start_hint = window.boundary_at
+        if self._open_window() is not None:
+            return
+        start = self._next_window_start_hint
+        if start is None or started_at < start:
+            start = _floor_second(started_at)
+        while started_at >= _window_boundary(start, self._flush_interval_sec):
+            start = _window_boundary(start, self._flush_interval_sec)
+        self._new_window(start)
+        self._next_window_start_hint = None
+
+    def _new_window(self, window_start: datetime) -> _MutableDbWindow:
+        key = self._next_window_key
+        self._next_window_key += 1
+        window_start = _floor_second(window_start)
+        window = _MutableDbWindow(
+            key=key,
+            window_start=window_start,
+            boundary_at=_window_boundary(window_start, self._flush_interval_sec),
+        )
+        self._windows[key] = window
+        self._open_window_key = key
+        return window
+
+    def _open_window(self) -> _MutableDbWindow | None:
+        if self._open_window_key is None:
+            return None
+        return self._windows.get(self._open_window_key)
+
+    def _seal_due(self, now: datetime) -> None:
+        now = _as_utc(now)
+        window = self._open_window()
+        if window is None or now < window.boundary_at:
+            return
+        self._seal_window(window, window.boundary_at)
+        self._open_window_key = None
+        self._next_window_start_hint = window.boundary_at
+
+    def _seal_open(self, now: datetime) -> None:
+        window = self._open_window()
+        if window is None:
+            return
+        self._seal_window(window, min(_as_utc(now), window.boundary_at))
+        self._open_window_key = None
+        self._next_window_start_hint = None
+
+    @staticmethod
+    def _seal_window(window: _MutableDbWindow, sealed_at: datetime) -> None:
+        if window.sealed_at is None:
+            window.sealed_at = max(window.window_start, sealed_at)
+
+    def _ready_windows(self) -> list[_MutableDbWindow]:
+        return sorted(
+            (
+                window
+                for window in self._windows.values()
+                if window.sealed_at is not None and not window.inflight
+            ),
+            key=lambda item: item.key,
+        )
+
+    def _deliver_ready_one(self) -> bool:
+        ready = self._ready_windows()
+        if not ready:
+            return False
+        window = ready[0]
+        frozen = self._freeze(window)
+        self._remove_window(window)
+        self._invoke_callback(frozen)
+        self._complete_flush_barriers(window.key)
+        return True
+
+    def _complete_flush_barriers(self, window_key: int) -> None:
+        remaining: list[_FlushBarrier] = []
+        for barrier in self._flush_barriers:
+            barrier.window_keys.discard(window_key)
+            if barrier.window_keys:
+                remaining.append(barrier)
+            else:
+                barrier.done.set()
+        self._flush_barriers = remaining
+
+    def _release_flush_barriers(self) -> None:
+        for barrier in self._flush_barriers:
+            barrier.done.set()
+        self._flush_barriers.clear()
+
+    def _seal_all_windows(self) -> None:
+        now = self._utc_now()
+        self._seal_open(now)
+        for window in self._windows.values():
+            if window.sealed_at is None:
+                self._seal_window(window, now)
+
+    def _deliver_all_after_close(self) -> None:
+        while True:
+            self._drain_after_deadline()
+            self._sync_ineligible_overflow()
+            self._seal_all_windows()
+            if not self._deliver_ready_one():
+                return
+
+    def _finish_close(self, record: _CloseRecord) -> None:
+        try:
+            while self._pending and self._monotonic() < record.deadline:
+                nested_close = self._drain_available(None)
+                if nested_close is not None:
+                    nested_close.done.set()
+                self._sync_ineligible_overflow()
+                self._seal_due(self._utc_now())
+                if self._deliver_ready_one():
+                    continue
+                remaining = max(0.0, record.deadline - self._monotonic())
+                try:
+                    next_record = self._records.get(timeout=remaining)
+                except queue.Empty:
+                    break
+                nested_close = self._drain_available(next_record)
+                if nested_close is not None:
+                    nested_close.done.set()
+            for observation_id in tuple(self._pending):
+                self._process_drop(observation_id, abandoned=True)
+            self._deliver_all_after_close()
+            with self._state_lock:
+                self._closed = True
+        finally:
+            self._release_flush_barriers()
+            record.done.set()
+
+    def _drain_after_deadline(self) -> None:
+        while True:
+            try:
+                record = self._records.get_nowait()
+            except queue.Empty:
+                return
+            if isinstance(record, _CloseRecord):
+                record.done.set()
+                continue
+            self._process(record)
+
+    def _freeze(self, window: _MutableDbWindow) -> _FrozenDbTimeBatch:
+        self._batch_seq += 1
+        batch_seq = self._batch_seq
+        batch_id = uuid.uuid5(self.pod_instance_id, str(batch_seq))
+        completed = tuple(
+            sorted(
+                window.observations.values(),
+                key=lambda item: item.pending.observation_id.hex,
+            )
+        )
+        observations = [
+            {
+                "observation_id": str(item.pending.observation_id),
+                "transaction_id": str(item.pending.transaction_id),
+                "request_id_hash": item.pending.request_id_hash,
+                "thread_id_hash": item.pending.thread_id_hash,
+                "trace_id": item.trace_id,
+                "span_id": item.span_id,
+                "linked_trace_id": item.linked_trace_id,
+                "customer_external_key": item.pending.customer_external_key,
+                "feature_key": item.pending.feature_key,
+                "started_at": _format_utc(item.pending.started_at),
+                "duration_ns": item.duration_ns,
+                "outcome": item.outcome,
+            }
+            for item in completed
+        ]
+        dropped_count = window.sampled_count - len(observations)
+        sealed_at = window.sealed_at or window.window_start
+        elapsed = max(0.0, (sealed_at - window.window_start).total_seconds())
+        seconds_until_midnight = (
+            _next_midnight(window.window_start) - window.window_start
+        ).total_seconds()
+        window_seconds = min(
+            300,
+            max(1, math.ceil(min(elapsed, seconds_until_midnight))),
+        )
+        payload = {
+            "schema_version": _SCHEMA_VERSION,
+            "service": self.service,
+            "pool_key": self.pool_key,
+            "pod_id": self.pod_id,
+            "pod_instance_id": str(self.pod_instance_id),
+            "batch_seq": batch_seq,
+            "batch_id": str(batch_id),
+            "window_start": _format_utc(window.window_start),
+            "window_seconds": window_seconds,
+            "sample_rate": format(
+                Decimal(str(self.sample_rate)).quantize(Decimal("0.00001")),
+                "f",
+            ),
+            "attempted_count": window.attempted_count,
+            "sampled_count": window.sampled_count,
+            "dropped_count": dropped_count,
+            "observations": observations,
+        }
+        body = json.dumps(
+            payload,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("utf-8")
+        return _FrozenDbTimeBatch(
+            body=body,
+            batch_id=batch_id,
+            batch_seq=batch_seq,
+            pod_instance_id=self.pod_instance_id,
+            service=self.service,
+            pool_key=self.pool_key,
+            pod_id=self.pod_id,
+            window_start=payload["window_start"],
+            attempted_count=window.attempted_count,
+            sampled_count=window.sampled_count,
+            dropped_count=dropped_count,
+            observations=completed,
+        )
+
+    def _remove_window(self, window: _MutableDbWindow) -> None:
+        self._windows.pop(window.key, None)
+        for observation_id in window.observations:
+            self._completed_locations.pop(observation_id, None)
+
+    def _invoke_callback(self, frozen: _FrozenDbTimeBatch) -> None:
+        callback = self._flush_callback
+        if callback is None:
+            outcome = _DbTimeFlushOutcome.DELIVERED
+        else:
+            callback_failed = False
+            try:
+                outcome = callback(frozen)
+                if not isinstance(outcome, _DbTimeFlushOutcome):
+                    callback_failed = True
+                    outcome = _DbTimeFlushOutcome.RETRY_EXHAUSTED
+            except Exception:
+                callback_failed = True
+                outcome = _DbTimeFlushOutcome.RETRY_EXHAUSTED
+            if callback_failed:
+                self._increment("callback_failures")
+                self._safe_log(
+                    "moolabs.attribution.db_time.callback_failure",
+                    {"batch_seq": frozen.batch_seq},
+                )
+        if outcome is _DbTimeFlushOutcome.DELIVERED:
+            self._increment("delivered_batches")
+        elif outcome is _DbTimeFlushOutcome.TERMINAL_DROP:
+            self._increment("terminal_dropped_batches")
+            self._safe_log(
+                "moolabs.attribution.db_time.terminal_drop",
+                {"batch_seq": frozen.batch_seq},
+            )
+        else:
+            self._increment("retry_exhausted_batches")
+            self._safe_log(
+                "moolabs.attribution.db_time.retry_exhausted",
+                {"batch_seq": frozen.batch_seq},
+            )
+
+    def _set_pending_count(self) -> None:
+        with self._state_lock:
+            self._stats["pending_count"] = len(self._pending)
+
+    def _increment(self, name: str, amount: int = 1) -> None:
+        with self._state_lock:
+            self._stats[name] += amount
+
+    def _safe_log(self, event_name: str, fields: dict[str, Any]) -> None:
+        if self._logger is None:
+            return
+        try:
+            self._logger(event_name, fields)
+        except Exception:
+            return
+
+
+class _DbTimeSpanProcessor(SpanProcessor):
+    def __init__(self, handle: DbTimeDriverHandle) -> None:
+        self._handle_ref = weakref.ref(handle)
+        self._lock = threading.Lock()
+        self._enabled = True
+
+    @property
+    def enabled(self) -> bool:
+        with self._lock:
+            return self._enabled
+
+    def disable(self) -> None:
+        with self._lock:
+            self._enabled = False
+
+    def on_start(
+        self,
+        span: Any,
+        parent_context: Context | None = None,
+    ) -> None:
+        del span, parent_context
+
+    def on_end(self, span: ReadableSpan) -> None:
+        try:
+            if not self.enabled or span.name != _SPAN_NAME:
+                return
+            attributes = span.attributes or {}
+            schema_version = attributes.get("moolabs.db_time.schema_version")
+            if type(schema_version) is not int or schema_version != _SCHEMA_VERSION:
+                return
+            comment = attributes.get("moolabs.db_time.sql_comment")
+            if not isinstance(comment, str):
+                return
+            match = _COMMENT_RE.fullmatch(comment)
+            if match is None:
+                return
+
+            handle = self._handle_ref()
+            if handle is None:
+                return
+            outcome = attributes.get("moolabs.db_time.outcome")
+            if outcome not in {"ok", "error"}:
+                return
+            start_time = span.start_time
+            end_time = span.end_time
+            if start_time is None or end_time is None:
+                return
+
+            linked_trace_id: str | None = None
+            for link in span.links:
+                if link.context.is_valid:
+                    linked_trace_id = f"{link.context.trace_id:032x}"
+                    break
+            handle._enqueue_span_end(
+                observation_id=uuid.UUID(hex=match.group(1)),
+                trace_id=f"{span.context.trace_id:032x}",
+                span_id=f"{span.context.span_id:016x}",
+                linked_trace_id=linked_trace_id,
+                duration_ns=max(0, int(end_time) - int(start_time)),
+                outcome=outcome,
+            )
+        except Exception:
+            return
+
+    def shutdown(self) -> None:
+        self.disable()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        del timeout_millis
+        return True
+
+
+class _ProviderDbTimeSpanProcessor(SpanProcessor):
+    """One provider-owned dispatcher for all live DB-time handles."""
+
+    def __init__(self) -> None:
+        self._process_id = os.getpid()
+        self._lock = threading.RLock()
+        self._processors: weakref.WeakSet[_DbTimeSpanProcessor] = weakref.WeakSet()
+        self._shutdown = False
+
+    def register(self, processor: _DbTimeSpanProcessor) -> None:
+        if self._process_id != os.getpid():
+            raise RuntimeError(
+                "inherited tracer_provider cannot be reused after fork; "
+                "create a child-owned tracer provider"
+            )
+        with self._lock:
+            if self._shutdown:
+                raise RuntimeError("tracer provider DB-time processor is shut down")
+            self._processors.add(processor)
+
+    def unregister(self, processor: _DbTimeSpanProcessor) -> None:
+        if self._process_id != os.getpid():
+            return
+        with self._lock:
+            self._processors.discard(processor)
+
+    def _snapshot(self) -> tuple[_DbTimeSpanProcessor, ...]:
+        if self._process_id != os.getpid():
+            return ()
+        with self._lock:
+            if self._shutdown:
+                return ()
+            return tuple(self._processors)
+
+    def on_start(
+        self,
+        span: Any,
+        parent_context: Context | None = None,
+    ) -> None:
+        for processor in self._snapshot():
+            try:
+                processor.on_start(span, parent_context)
+            except Exception:
+                continue
+
+    def on_end(self, span: ReadableSpan) -> None:
+        for processor in self._snapshot():
+            try:
+                processor.on_end(span)
+            except Exception:
+                continue
+
+    def shutdown(self) -> None:
+        if self._process_id != os.getpid():
+            return
+        with self._lock:
+            if self._shutdown:
+                return
+            self._shutdown = True
+            processors = tuple(self._processors)
+            self._processors.clear()
+        for processor in processors:
+            try:
+                processor.shutdown()
+            except Exception:
+                continue
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        successful = True
+        for processor in self._snapshot():
+            try:
+                successful = processor.force_flush(timeout_millis) and successful
+            except Exception:
+                successful = False
+        return successful
+
+
+class DbTimeDriverHandle:
+    """Own SQLAlchemy listeners and the local redacted span processor."""
+
+    def __init__(
+        self,
+        sync_engine: Engine,
+        config: _InstallConfig,
+        tracer_provider: Any,
+        *,
+        pod_id: str,
+        queue_capacity: int,
+        overflow_bucket_capacity: int,
+        batch_size: int,
+        flush_interval_sec: float,
+        shutdown_timeout_sec: float,
+        flush_callback: DbTimeFlushCallback | None,
+        logger: Callable[[str, dict[str, Any]], None] | None,
+        utc_now: Callable[[], datetime],
+        monotonic: Callable[[], float],
+    ) -> None:
+        self._process_id = os.getpid()
+        self.sync_engine = sync_engine
+        self.service = config.service
+        self.pool_key = config.pool_key
+        self.sample_rate = config.sample_rate
+        self._config = config
+        self._tracer_provider = tracer_provider
+        self._tracer: Any = None
+        self._tracer_lock = threading.Lock()
+        self._shutdown_timeout_sec = shutdown_timeout_sec
+        self._utc_now = utc_now
+        self._monotonic = monotonic
+        self._owner = _DbTimeWindowOwner(
+            service=self.service,
+            pool_key=self.pool_key,
+            pod_id=pod_id,
+            sample_rate=self.sample_rate,
+            queue_capacity=queue_capacity,
+            overflow_bucket_capacity=overflow_bucket_capacity,
+            batch_size=batch_size,
+            flush_interval_sec=flush_interval_sec,
+            flush_callback=flush_callback,
+            logger=logger,
+            utc_now=utc_now,
+            monotonic=monotonic,
+        )
+        self.pod_id = pod_id
+        self.pod_instance_id = self._owner.pod_instance_id
+        self._worker = self._owner.thread
+        self._processor = _DbTimeSpanProcessor(self)
+        self._provider_processor: _ProviderDbTimeSpanProcessor | None = None
+        self._listeners: list[tuple[Any, str, Callable[..., Any]]] = []
+        self._state_lock = threading.RLock()
+        self._start_gate = threading.RLock()
+        self._close_complete = threading.Event()
+        self._closed = False
+        self._accepting_starts = True
+        self._finalizer = weakref.finalize(
+            self,
+            DbTimeDriverHandle._finalize_owner,
+            self._owner,
+            self._monotonic,
+            self._process_id,
+        )
+
+    def _is_current_process(self) -> bool:
+        return self._process_id == os.getpid()
+
+    def _require_current_process(self) -> None:
+        if not self._is_current_process():
+            raise RuntimeError(
+                "DB-time handle belongs to a parent process; install a child-owned handle"
+            )
+
+    @property
+    def closed(self) -> bool:
+        if not self._is_current_process():
+            return True
+        with self._state_lock:
+            return self._closed
+
+    def __enter__(self) -> DbTimeDriverHandle:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        del exc_info
+        self.close()
+
+    def stats(self) -> dict[str, int]:
+        self._require_current_process()
+        return self._owner.stats()
+
+    def flush(self) -> None:
+        self._require_current_process()
+        self._owner.flush(force=True)
+
+    def flush_ready_windows(self) -> None:
+        self._require_current_process()
+        self._owner.flush(force=False)
+
+    def close(self) -> None:
+        if not self._is_current_process():
+            return
+        with self._state_lock:
+            if self._closed:
+                close_complete = self._close_complete
+                if threading.current_thread() is self._worker:
+                    return
+            else:
+                self._closed = True
+                close_complete = None
+
+        if close_complete is not None:
+            close_complete.wait()
+            if self._worker.is_alive():
+                self._worker.join()
+            return
+
+        with self._start_gate:
+            self._accepting_starts = False
+
+        deadline = self._monotonic() + self._shutdown_timeout_sec
+        done = self._owner.request_close(deadline)
+        current_worker = threading.current_thread() is self._worker
+        if current_worker:
+            threading.Thread(
+                target=self._complete_close,
+                args=(done,),
+                name="moolabs-db-time-close",
+                daemon=True,
+            ).start()
+            return
+        self._complete_close(done)
+
+    def _complete_close(self, done: threading.Event) -> None:
+        try:
+            done.wait()
+            if self._worker.is_alive():
+                self._worker.join()
+            self._remove_listeners()
+            provider_processor = self._provider_processor
+            self._provider_processor = None
+            self._processor.disable()
+            if provider_processor is not None:
+                provider_processor.unregister(self._processor)
+            with _INSTALLS_LOCK:
+                installed = _INSTALLS.get(self.sync_engine)
+                if installed is not None and installed() is self:
+                    del _INSTALLS[self.sync_engine]
+            self._finalizer.detach()
+        finally:
+            self._close_complete.set()
+
+    def _remove_listeners(self) -> None:
+        for target, identifier, listener in reversed(self._listeners):
+            try:
+                event.remove(target, identifier, listener)
+            except Exception:
+                continue
+        self._listeners.clear()
+
+    @staticmethod
+    def _finalize_owner(
+        owner: _DbTimeWindowOwner,
+        monotonic: Callable[[], float],
+        process_id: int,
+    ) -> None:
+        if process_id != os.getpid():
+            return
+        owner.request_close(monotonic())
+
+    def _register_listeners(self) -> None:
+        listeners: tuple[tuple[Any, str, Callable[..., Any], bool], ...] = (
+            (self.sync_engine, "begin", self._on_begin, False),
+            (self.sync_engine, "commit", self._on_commit, False),
+            (self.sync_engine, "rollback", self._on_rollback, False),
+            (self.sync_engine, "savepoint", self._on_savepoint, False),
+            (
+                self.sync_engine,
+                "rollback_savepoint",
+                self._on_rollback_savepoint,
+                False,
+            ),
+            (
+                self.sync_engine,
+                "release_savepoint",
+                self._on_release_savepoint,
+                False,
+            ),
+            (
+                self.sync_engine,
+                "before_cursor_execute",
+                self._before_cursor_execute,
+                True,
+            ),
+            (
+                self.sync_engine,
+                "after_cursor_execute",
+                self._after_cursor_execute,
+                False,
+            ),
+            (self.sync_engine, "handle_error", self._handle_error, False),
+            (self.sync_engine, "checkin", self._on_checkin, False),
+        )
+        try:
+            for target, identifier, listener, returns_value in listeners:
+                if returns_value:
+                    event.listen(target, identifier, listener, retval=True)
+                else:
+                    event.listen(target, identifier, listener)
+                self._listeners.append((target, identifier, listener))
+        except Exception:
+            for target, identifier, listener in reversed(self._listeners):
+                try:
+                    event.remove(target, identifier, listener)
+                except Exception:
+                    continue
+            raise
+
+    def _get_tracer(self) -> Any:
+        with self._tracer_lock:
+            if self._tracer is None:
+                self._tracer = self._tracer_provider.get_tracer(
+                    "moolabs.db_time",
+                    "1",
+                )
+            return self._tracer
+
+    def _enqueue_start(
+        self,
+        pending: _PendingDbObservation | None,
+        *,
+        started_at: datetime | None = None,
+    ) -> None:
+        if not self._is_current_process():
+            return
+        with self._start_gate:
+            if not self._accepting_starts:
+                return
+            self._owner.submit(
+                _StartRecord(
+                    started_at=started_at
+                    or (pending.started_at if pending else self._utc_now()),
+                    pending=pending,
+                )
+            )
+
+    def _enqueue_span_end(
+        self,
+        *,
+        observation_id: uuid.UUID,
+        trace_id: str,
+        span_id: str,
+        linked_trace_id: str | None,
+        duration_ns: int,
+        outcome: Literal["ok", "error"],
+    ) -> None:
+        if not self._is_current_process():
+            return
+        self._owner.submit(
+            _EndRecord(
+                observation_id=observation_id,
+                trace_id=trace_id,
+                span_id=span_id,
+                linked_trace_id=linked_trace_id,
+                duration_ns=duration_ns,
+                outcome=outcome,
+            )
+        )
+
+    def _enqueue_completed(self, completed: _CompletedDbObservation) -> None:
+        self._enqueue_span_end(
+            observation_id=completed.pending.observation_id,
+            trace_id=completed.trace_id,
+            span_id=completed.span_id,
+            linked_trace_id=completed.linked_trace_id,
+            duration_ns=completed.duration_ns,
+            outcome=completed.outcome,
+        )
+
+    def _enqueue_drop(self, observation_key: str | None) -> None:
+        if not self._is_current_process():
+            return
+        if observation_key is None:
+            return
+        try:
+            observation_id = uuid.UUID(hex=observation_key)
+        except (ValueError, AttributeError):
+            return
+        self._owner.submit(_DropRecord(observation_id))
+
+    def _on_begin(self, connection: Any) -> None:
+        if not self._is_current_process():
+            return
+        try:
+            connection.info[_TRANSACTION_ID_KEY] = uuid.uuid4()
+        except Exception:
+            return
+
+    def _on_commit(self, connection: Any) -> None:
+        if not self._is_current_process():
+            return
+        self._clear_transaction(connection)
+
+    def _on_rollback(self, connection: Any) -> None:
+        if not self._is_current_process():
+            return
+        self._clear_transaction(connection)
+
+    def _on_savepoint(self, connection: Any, name: str | None) -> None:
+        del connection, name
+
+    def _on_rollback_savepoint(
+        self,
+        connection: Any,
+        name: str | None,
+        context: Any,
+    ) -> None:
+        del connection, name, context
+
+    def _on_release_savepoint(
+        self,
+        connection: Any,
+        name: str | None,
+        context: Any,
+    ) -> None:
+        del connection, name, context
+
+    def _on_checkin(self, dbapi_connection: Any, connection_record: Any) -> None:
+        del dbapi_connection
+        if not self._is_current_process():
+            return
+        try:
+            connection_record.info.pop(_TRANSACTION_ID_KEY, None)
+        except Exception:
+            return
+
+    def _clear_transaction(self, connection: Any) -> None:
+        if not self._is_current_process():
+            return
+        try:
+            connection.info.pop(_TRANSACTION_ID_KEY, None)
+        except Exception:
+            return
+
+    def _transaction_id(self, connection: Any) -> tuple[uuid.UUID, bool]:
+        try:
+            current = connection.info.get(_TRANSACTION_ID_KEY)
+            if isinstance(current, uuid.UUID):
+                return current, False
+            statement_local = uuid.uuid4()
+            connection.info[_TRANSACTION_ID_KEY] = statement_local
+            return statement_local, True
+        except Exception:
+            return uuid.uuid4(), True
+
+    def _before_cursor_execute(
+        self,
+        connection: Any,
+        cursor: Any,
+        statement: str,
+        parameters: Any,
+        context: Any,
+        executemany: bool,
+    ) -> tuple[str, Any]:
+        del cursor, executemany
+        if not self._is_current_process():
+            return statement, parameters
+        with self._start_gate:
+            if not self._accepting_starts:
+                return statement, parameters
+            return self._instrument_statement_start(
+                connection,
+                statement,
+                parameters,
+                context,
+            )
+
+    def _instrument_statement_start(
+        self,
+        connection: Any,
+        statement: str,
+        parameters: Any,
+        context: Any,
+    ) -> tuple[str, Any]:
+        observation_id = uuid.uuid4()
+        observation_key = observation_id.hex
+        comment = f"/*moolabs_db_time:v1;ob={observation_key}*/"
+        prefixed_statement = f"{comment} {statement}"
+        statement_local = False
+        try:
+            started_at = _as_utc(self._utc_now())
+        except Exception:
+            started_at = datetime.now(timezone.utc)
+
+        span: Any = None
+        start_enqueued = False
+        sampled_start_enqueued = False
+        try:
+            transaction_id, statement_local = self._transaction_id(connection)
+            pending = _pending_observation(
+                observation_id,
+                transaction_id,
+                started_at=started_at,
+            )
+            parent = trace.get_current_span().get_span_context()
+            links = [Link(parent)] if parent.is_valid else []
+            span = self._get_tracer().start_span(
+                _SPAN_NAME,
+                context=Context(),
+                kind=SpanKind.CLIENT,
+                links=links,
+            )
+            span_context = span.get_span_context()
+            sampled = bool(span_context.trace_flags & TraceFlags.SAMPLED)
+            state = _StatementState(
+                span=span,
+                observation_key=observation_key if sampled else None,
+                sampled=sampled,
+                statement_local_transaction=statement_local,
+            )
+            if sampled:
+                values = (
+                    "postgresql",
+                    _SCHEMA_VERSION,
+                    comment,
+                    observation_key,
+                    self.service,
+                    self.pool_key,
+                )
+                for attribute, value in zip(
+                    _ALLOWED_SPAN_ATTRIBUTES,
+                    values,
+                    strict=True,
+                ):
+                    span.set_attribute(attribute, value)
+            setattr(context, _STATEMENT_STATE_KEY, state)
+            self._enqueue_start(pending if sampled else None, started_at=started_at)
+            start_enqueued = True
+            sampled_start_enqueued = sampled
+        except Exception:
+            if not start_enqueued:
+                try:
+                    self._enqueue_start(None, started_at=started_at)
+                except Exception:
+                    pass
+            elif sampled_start_enqueued:
+                self._enqueue_drop(observation_key)
+            if span is not None:
+                try:
+                    span.end()
+                except Exception:
+                    pass
+            if statement_local:
+                self._clear_transaction(connection)
+        return prefixed_statement, parameters
+
+    def _after_cursor_execute(
+        self,
+        connection: Any,
+        cursor: Any,
+        statement: str,
+        parameters: Any,
+        context: Any,
+        executemany: bool,
+    ) -> None:
+        del cursor, statement, parameters, executemany
+        if not self._is_current_process():
+            return
+        try:
+            self._finish_statement(connection, context, "ok")
+        except Exception:
+            return
+
+    def _handle_error(self, exception_context: Any) -> None:
+        if not self._is_current_process():
+            return None
+        try:
+            self._finish_statement(
+                exception_context.connection,
+                exception_context.execution_context,
+                "error",
+            )
+        except Exception:
+            return None
+        return None
+
+    def _finish_statement(
+        self,
+        connection: Any,
+        context: Any,
+        outcome: Literal["ok", "error"],
+    ) -> None:
+        if not self._is_current_process():
+            return
+        state = getattr(context, _STATEMENT_STATE_KEY, None)
+        if not isinstance(state, _StatementState) or not state.mark_ended():
+            return
+        try:
+            if state.sampled:
+                try:
+                    state.span.set_attribute("moolabs.db_time.outcome", outcome)
+                except Exception:
+                    self._enqueue_drop(state.observation_key)
+            try:
+                state.span.end()
+            except Exception:
+                self._enqueue_drop(state.observation_key)
+        finally:
+            if state.statement_local_transaction:
+                self._clear_transaction(connection)
+            try:
+                delattr(context, _STATEMENT_STATE_KEY)
+            except Exception:
+                pass
+
+
+_PROCESS_ID = os.getpid()
+_INSTALLS_LOCK = threading.RLock()
+_INSTALLS: weakref.WeakKeyDictionary[
+    Engine,
+    weakref.ReferenceType[DbTimeDriverHandle],
+] = weakref.WeakKeyDictionary()
+_PROVIDER_PROCESSORS_LOCK = threading.RLock()
+_PROVIDER_PROCESSORS: weakref.WeakKeyDictionary[
+    Any,
+    _ProviderDbTimeSpanProcessor,
+] = weakref.WeakKeyDictionary()
+
+
+def _ensure_process_state() -> None:
+    global _PROCESS_ID
+    global _INSTALLS_LOCK, _INSTALLS
+    global _PROVIDER_PROCESSORS_LOCK
+
+    process_id = os.getpid()
+    if process_id == _PROCESS_ID:
+        return
+    _INSTALLS_LOCK = threading.RLock()
+    _INSTALLS = weakref.WeakKeyDictionary()
+    _PROVIDER_PROCESSORS_LOCK = threading.RLock()
+    _PROCESS_ID = process_id
+
+
+def _provider_db_time_processor(provider: Any) -> _ProviderDbTimeSpanProcessor:
+    _validate_provider_process(provider)
+    with _PROVIDER_PROCESSORS_LOCK:
+        processor = _PROVIDER_PROCESSORS.get(provider)
+        if processor is not None:
+            return processor
+        _validate_provider_registration_available(provider)
+        processor = _ProviderDbTimeSpanProcessor()
+        provider.add_span_processor(processor)
+        _PROVIDER_PROCESSORS[provider] = processor
+        return processor
+
+
+def _validate_provider_process(provider: Any) -> None:
+    try:
+        weakref.ref(provider)
+    except TypeError as exc:
+        raise TypeError("tracer_provider must support weak references") from exc
+
+    with _PROVIDER_PROCESSORS_LOCK:
+        processor = _PROVIDER_PROCESSORS.get(provider)
+    if processor is not None and processor._process_id != os.getpid():
+        raise RuntimeError(
+            "inherited tracer_provider cannot be reused after fork; "
+            "create a child-owned tracer provider"
+        )
+
+
+def _validate_provider_registration_available(provider: Any) -> None:
+    active_processor = getattr(provider, "_active_span_processor", None)
+    registrar_lock = getattr(active_processor, "_lock", None)
+    lock_is_held = getattr(registrar_lock, "locked", None)
+    if not callable(lock_is_held):
+        raise TypeError(
+            "tracer_provider must be an OpenTelemetry SDK TracerProvider with "
+            "a detectable processor registrar"
+        )
+    if lock_is_held():
+        raise RuntimeError(
+            "tracer_provider processor registrar is locked; after fork, create "
+            "a child-owned tracer provider"
+        )
+
+
+def _python_version() -> tuple[int, int, int]:
+    return sys.version_info[:3]
+
+
+def _distribution_version(package: str) -> str:
+    return metadata.version(package)
+
+
+def _version_tuple(value: str) -> tuple[int, int, int]:
+    match = re.match(r"^(\d+)\.(\d+)(?:\.(\d+))?", value)
+    if match is None:
+        raise ValueError(f"unrecognized package version {value!r}")
+    return tuple(int(part or 0) for part in match.groups())  # type: ignore[return-value]
+
+
+def _installed_driver_version(driver: str) -> str:
+    packages = ("psycopg2", "psycopg2-binary") if driver == "psycopg2" else (driver,)
+    for package in packages:
+        try:
+            return _distribution_version(package)
+        except metadata.PackageNotFoundError:
+            continue
+    raise metadata.PackageNotFoundError(driver)
+
+
+def _validate_runtime_versions(driver: str) -> None:
+    python_version = _python_version()
+    if not (python_version >= (3, 10, 0) and python_version < (3, 13, 0)):
+        actual = ".".join(str(part) for part in python_version)
+        raise RuntimeError(f"unsupported Python {actual}; requires Python >=3.10,<3.13")
+
+    try:
+        sqlalchemy_version = _distribution_version("SQLAlchemy")
+    except metadata.PackageNotFoundError as exc:
+        raise RuntimeError("requires SQLAlchemy >=1.4.54,<2.1") from exc
+    parsed_sqlalchemy = _version_tuple(sqlalchemy_version)
+    if not ((1, 4, 54) <= parsed_sqlalchemy < (2, 1, 0)):
+        raise RuntimeError(
+            f"unsupported SQLAlchemy {sqlalchemy_version}; "
+            "requires SQLAlchemy >=1.4.54,<2.1"
+        )
+
+    try:
+        otel_api = _distribution_version("opentelemetry-api")
+        otel_sdk = _distribution_version("opentelemetry-sdk")
+    except metadata.PackageNotFoundError as exc:
+        raise RuntimeError("requires OpenTelemetry API/SDK 1.27.0") from exc
+    if otel_api != "1.27.0" or otel_sdk != "1.27.0":
+        raise RuntimeError(
+            f"unsupported OpenTelemetry API/SDK {otel_api}/{otel_sdk}; "
+            "requires OpenTelemetry API/SDK 1.27.0"
+        )
+
+    requirements = {
+        "psycopg2": ((2, 9, 9), (3, 0, 0), "psycopg2 >=2.9.9,<3"),
+        "psycopg": ((3, 1, 18), (4, 0, 0), "psycopg >=3.1.18,<4"),
+        "asyncpg": ((0, 29, 0), (1, 0, 0), "asyncpg >=0.29,<1"),
+    }
+    requirement = requirements.get(driver)
+    if requirement is None:
+        raise RuntimeError(
+            "PostgreSQL DB-time instrumentation requires psycopg2, psycopg, or asyncpg"
+        )
+    minimum, maximum, label = requirement
+    try:
+        driver_version = _installed_driver_version(driver)
+    except metadata.PackageNotFoundError as exc:
+        raise RuntimeError(f"requires {label}") from exc
+    if not (minimum <= _version_tuple(driver_version) < maximum):
+        raise RuntimeError(f"unsupported {driver} {driver_version}; requires {label}")
+
+
+def _validate_text(value: Any, name: str, maximum: int) -> str:
+    if (
+        not isinstance(value, str)
+        or value != value.strip()
+        or not 1 <= len(value) <= maximum
+        or not value.isprintable()
+    ):
+        raise ValueError(
+            f"{name} must be a trimmed printable string of 1-{maximum} characters"
+        )
+    return value
+
+
+def _resolve_pod_id(explicit_pod_id: str | None) -> str:
+    if explicit_pod_id is not None:
+        candidate = explicit_pod_id
+    else:
+        environment_hostname = os.environ.get("HOSTNAME", "").strip()
+        candidate = environment_hostname or socket.gethostname()
+    return _validate_text(candidate, "pod_id", 128)
+
+
+def _validate_pool_key(value: Any) -> str:
+    if not isinstance(value, str) or _POOL_KEY_RE.fullmatch(value) is None:
+        raise ValueError(
+            "pool_key must match lowercase ASCII [a-z0-9][a-z0-9_.-]{0,47}"
+        )
+    return value
+
+
+def _validate_sample_rate(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("sample_rate must be a finite number in (0,1]")
+    normalized = float(value)
+    if not math.isfinite(normalized) or not 0 < normalized <= 1:
+        raise ValueError("sample_rate must be a finite number in (0,1]")
+    try:
+        decimal = Decimal(str(value))
+    except InvalidOperation as exc:
+        raise ValueError("sample_rate must have at most five decimal places") from exc
+    if decimal.as_tuple().exponent < -5:
+        raise ValueError("sample_rate must have at most five decimal places")
+    return normalized
+
+
+def _validate_integer(
+    value: Any,
+    name: str,
+    *,
+    minimum: int,
+    maximum: int,
+) -> int:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be an integer in [{minimum}, {maximum}]")
+    return value
+
+
+def _validate_seconds(
+    value: Any,
+    name: str,
+    *,
+    positive: bool,
+    maximum: float | None = None,
+) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a finite number")
+    normalized = float(value)
+    valid = normalized > 0 if positive else normalized >= 0
+    if not math.isfinite(normalized) or not valid:
+        bound = "positive" if positive else "non-negative"
+        raise ValueError(f"{name} must be finite and {bound}")
+    if maximum is not None and normalized > maximum:
+        raise ValueError(f"{name} must be at most {maximum}")
+    return normalized
+
+
+def _overflow_bucket_capacity(
+    flush_callback: DbTimeFlushCallback | None,
+    *,
+    flush_interval_sec: float,
+    shutdown_timeout_sec: float,
+) -> int:
+    blocking_bound = max(flush_interval_sec, shutdown_timeout_sec)
+    callback_bound = getattr(flush_callback, "max_blocking_seconds", None)
+    if (
+        not isinstance(callback_bound, bool)
+        and isinstance(callback_bound, (int, float))
+        and math.isfinite(float(callback_bound))
+        and float(callback_bound) >= 0
+    ):
+        blocking_bound = max(blocking_bound, float(callback_bound))
+    return max(2, math.ceil(blocking_bound) + 3)
+
+
+def _callable_identity(
+    callback: Callable[..., Any] | None,
+) -> tuple[int | None, int] | None:
+    if callback is None:
+        return None
+    owner = getattr(callback, "__self__", None)
+    function = getattr(callback, "__func__", callback)
+    return (id(owner) if owner is not None else None, id(function))
+
+
+def _normalize_engine(engine: Any) -> tuple[Engine, bool]:
+    if isinstance(engine, AsyncEngine):
+        return engine.sync_engine, True
+    if isinstance(engine, Engine):
+        return engine, False
+    raise TypeError("engine must be a SQLAlchemy Engine or AsyncEngine")
+
+
+def _validate_engine(sync_engine: Engine, is_async: bool) -> str:
+    dialect = getattr(sync_engine, "dialect", None)
+    if dialect is None or getattr(dialect, "name", None) != "postgresql":
+        raise ValueError("DB-time instrumentation supports PostgreSQL engines only")
+    driver = getattr(dialect, "driver", None)
+    if not isinstance(driver, str):
+        raise ValueError("PostgreSQL engine driver could not be identified")
+    if is_async and driver != "asyncpg":
+        raise RuntimeError("AsyncEngine DB-time instrumentation requires asyncpg")
+    if not is_async and driver == "asyncpg":
+        raise RuntimeError("asyncpg DB-time instrumentation requires AsyncEngine")
+    return driver
+
+
+def _validate_provider(provider: Any) -> None:
+    if not callable(getattr(provider, "get_tracer", None)):
+        raise TypeError("tracer_provider must provide get_tracer")
+    if not callable(getattr(provider, "add_span_processor", None)):
+        raise TypeError("tracer_provider must provide add_span_processor")
+
+
+def _validate_sampler_parity(provider: Any, sample_rate: float) -> None:
+    sampler = getattr(provider, "sampler", None)
+    if isinstance(sampler, ParentBased):
+        sampler = getattr(sampler, "_root", None)
+
+    probability: Any = None
+    if isinstance(sampler, TraceIdRatioBased):
+        probability = getattr(sampler, "_rate", None)
+    elif callable(getattr(sampler, "get_description", None)):
+        if sampler.get_description() == "AlwaysOnSampler":
+            probability = 1.0
+
+    if (
+        isinstance(probability, bool)
+        or not isinstance(probability, (int, float))
+        or not math.isfinite(float(probability))
+    ):
+        raise RuntimeError(
+            "root sampler probability cannot be derived; configure "
+            "AlwaysOnSampler or TraceIdRatioBased"
+        )
+    if Decimal(str(probability)) != Decimal(str(sample_rate)):
+        raise RuntimeError(
+            f"root sampler probability {probability} must equal "
+            f"declared sample_rate {sample_rate}"
+        )
+
+
+def _correlation_hash(kind: Literal["request", "thread"], value: str) -> str:
+    return hashlib.sha256(
+        f"moolabs:db-time:v1:{kind}:{value}".encode("utf-8")
+    ).hexdigest()
+
+
+def _pending_observation(
+    observation_id: uuid.UUID,
+    transaction_id: uuid.UUID,
+    *,
+    started_at: datetime | None = None,
+) -> _PendingDbObservation:
+    context = get_attribution_context()
+    if context is None:
+        customer_external_key, feature_key = _UNATTRIBUTED_IDENTITY_PAIR
+        request_id_hash = None
+        thread_id_hash = None
+    else:
+        dimensions = _normalized_dimensions(
+            context.customer_external_key,
+            context.feature_key,
+            context.thread_id,
+        )
+        if dimensions is None:
+            customer_external_key, feature_key = _UNATTRIBUTED_IDENTITY_PAIR
+            request_id_hash = None
+            thread_id_hash = None
+        else:
+            customer_external_key, feature_key, thread_id = dimensions
+            request_id_hash = _correlation_hash("request", context.request_id)
+            thread_id_hash = _correlation_hash("thread", thread_id)
+    return _PendingDbObservation(
+        observation_id=observation_id,
+        transaction_id=transaction_id,
+        request_id_hash=request_id_hash,
+        thread_id_hash=thread_id_hash,
+        customer_external_key=customer_external_key,
+        feature_key=feature_key,
+        started_at=_as_utc(started_at or datetime.now(timezone.utc)),
+    )
+
+
+def install_db_time_driver(
+    engine: Any,
+    *,
+    service: str,
+    pool_key: str,
+    sample_rate: float,
+    pod_id: str | None = None,
+    tracer_provider: Any = None,
+    queue_capacity: int = 5000,
+    batch_size: int = 500,
+    flush_interval_sec: float = 5.0,
+    shutdown_timeout_sec: float = 60.0,
+    flush_callback: DbTimeFlushCallback | None = None,
+    logger: Callable[[str, dict[str, Any]], None] | None = None,
+    _utc_now: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
+    _monotonic: Callable[[], float] = time.monotonic,
+) -> DbTimeDriverHandle:
+    """Install one redacted DB-time listener set on a PostgreSQL engine."""
+    _ensure_process_state()
+    normalized_service = _validate_text(service, "service", 128)
+    normalized_pool_key = _validate_pool_key(pool_key)
+    normalized_sample_rate = _validate_sample_rate(sample_rate)
+    normalized_pod_id = _resolve_pod_id(pod_id)
+    normalized_queue_capacity = _validate_integer(
+        queue_capacity,
+        "queue_capacity",
+        minimum=1,
+        maximum=1_000_000,
+    )
+    normalized_batch_size = _validate_integer(
+        batch_size,
+        "batch_size",
+        minimum=1,
+        maximum=500,
+    )
+    normalized_flush_interval = _validate_seconds(
+        flush_interval_sec,
+        "flush_interval_sec",
+        positive=True,
+        maximum=300.0,
+    )
+    normalized_shutdown_timeout = _validate_seconds(
+        shutdown_timeout_sec,
+        "shutdown_timeout_sec",
+        positive=False,
+    )
+    if flush_callback is not None and not callable(flush_callback):
+        raise ValueError("flush_callback must be callable")
+    if logger is not None and not callable(logger):
+        raise ValueError("logger must be callable")
+    if not callable(_utc_now) or not callable(_monotonic):
+        raise ValueError("clock functions must be callable")
+    overflow_bucket_capacity = _overflow_bucket_capacity(
+        flush_callback,
+        flush_interval_sec=normalized_flush_interval,
+        shutdown_timeout_sec=normalized_shutdown_timeout,
+    )
+
+    sync_engine, is_async = _normalize_engine(engine)
+    driver = _validate_engine(sync_engine, is_async)
+    _validate_runtime_versions(driver)
+    provider = tracer_provider or trace.get_tracer_provider()
+    _validate_provider(provider)
+    _validate_provider_process(provider)
+    config = _InstallConfig(
+        service=normalized_service,
+        pool_key=normalized_pool_key,
+        sample_rate=normalized_sample_rate,
+        tracer_provider_identity=id(provider),
+        flush_callback_identity=_callable_identity(flush_callback),
+    )
+
+    with _INSTALLS_LOCK:
+        existing_ref = _INSTALLS.get(sync_engine)
+        existing = existing_ref() if existing_ref is not None else None
+        if existing_ref is not None and existing is None:
+            del _INSTALLS[sync_engine]
+        if existing is not None and not existing.closed:
+            if existing._config == config:
+                return existing
+            raise ValueError(
+                "SQLAlchemy engine is already instrumented with conflicting "
+                "service, pool_key, sample_rate, tracer provider, or transport owner"
+            )
+
+        _validate_sampler_parity(provider, normalized_sample_rate)
+        handle = DbTimeDriverHandle(
+            sync_engine,
+            config,
+            provider,
+            pod_id=normalized_pod_id,
+            queue_capacity=normalized_queue_capacity,
+            overflow_bucket_capacity=overflow_bucket_capacity,
+            batch_size=normalized_batch_size,
+            flush_interval_sec=normalized_flush_interval,
+            shutdown_timeout_sec=normalized_shutdown_timeout,
+            flush_callback=flush_callback,
+            logger=logger,
+            utc_now=_utc_now,
+            monotonic=_monotonic,
+        )
+        provider_processor: _ProviderDbTimeSpanProcessor | None = None
+        try:
+            provider_processor = _provider_db_time_processor(provider)
+            handle._provider_processor = provider_processor
+            provider_processor.register(handle._processor)
+            handle._register_listeners()
+        except Exception:
+            handle._processor.disable()
+            if provider_processor is not None:
+                provider_processor.unregister(handle._processor)
+            handle._provider_processor = None
+            handle.close()
+            raise
+        _INSTALLS[sync_engine] = weakref.ref(handle)
+        return handle