signal-bot/signal_bot/analytics/health.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Family C: which commands are broken, slow, or refusing people.

This is the family that had *no* data at all before ``command_events``:
``store.record_use`` fires only on success, so a command that crashed every
time was indistinguishable from one nobody ran.

Latency narrows to ``live``. A reconstructed row has no duration -- NULL,
never 0, because a zero would drag a p50 down and read as a fast command.
Every aggregate here therefore says ``handler_ms IS NOT NULL`` rather than
relying on the source column, so a future third source with real timings
would be included automatically and one without would not.
"""

from __future__ import annotations

import math
from dataclasses import dataclass
from typing import TYPE_CHECKING, Final

if TYPE_CHECKING:
    import sqlite3

    from signal_bot.analytics.scope import Scope

# Which percentiles the panel shows. The median says what it is usually
# like; the 95th says what it is like when somebody complains.
P50: Final = 0.50
P95: Final = 0.95


@dataclass(frozen=True, slots=True)
class Latency:
    """How long one command takes, split the way DOCS-latency.md splits it."""

    command: str
    samples: int
    handler_p50: int
    handler_p95: int
    send_p50: int
    upstream_p50: int


@dataclass(frozen=True, slots=True)
class Upstream:
    """One external service, and how well it has been behaving."""

    host: str
    calls: int
    failures: int
    p50_ms: int

    @property
    def failure_rate(self) -> float:
        """Share of calls that were not a 2xx."""
        return self.failures / self.calls if self.calls else 0.0


GATES_SQL: Final = """
SELECT command, outcome, COUNT(*) AS n
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome LIKE 'refused_%'
GROUP BY command, outcome
ORDER BY n DESC, command
"""

ERRORS_SQL: Final = """
SELECT command, error_class, COUNT(*) AS n
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome = 'error'
GROUP BY command, error_class
ORDER BY n DESC, command
"""

TIMED_SQL: Final = """
SELECT command, handler_ms, send_ms
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND handler_ms IS NOT NULL
ORDER BY command, handler_ms
"""

UPSTREAM_SQL: Final = """
SELECT host,
       COUNT(*)                          AS calls,
       SUM(status < 200 OR status > 299) AS failures
FROM upstream_calls
WHERE (:group IS NULL OR group_id = :group)
GROUP BY host
ORDER BY calls DESC, host
"""

UPSTREAM_TIMES_SQL: Final = """
SELECT host, duration_ms
FROM upstream_calls
WHERE (:group IS NULL OR group_id = :group)
ORDER BY host, duration_ms
"""

COMMAND_UPSTREAM_SQL: Final = """
SELECT command, duration_ms
FROM upstream_calls
WHERE (:group IS NULL OR group_id = :group)
ORDER BY command, duration_ms
"""


def percentile(sorted_values: list[int], fraction: float) -> int:
    """The value at a fraction of the way through an already-sorted list.

    Nearest-rank: ``ceil(p * n) - 1``, so the answer is always one of the
    measurements rather than an interpolation between two of them. A p95
    that nobody actually experienced is a worse number to act on than a
    real one that is slightly off the theoretical quantile.

    Spelled with ``math.ceil`` rather than ``round`` deliberately. Python
    rounds halves to even, so ``round(0.5)`` is 0 and ``round(1.5)`` is 2 --
    which would make the median of a two-element sample depend on the
    sample's length in a way no reader would predict.

    Computed here rather than in SQL: SQLite has no percentile function
    without an extension, and adding one would mean a seventh dependency for
    three lines of arithmetic.
    """
    if not sorted_values:
        return 0
    rank = math.ceil(fraction * len(sorted_values)) - 1
    return sorted_values[max(0, min(len(sorted_values) - 1, rank))]


def latencies(conn: sqlite3.Connection, scope: Scope) -> list[Latency]:
    """Per-command timings, from the rows that actually carry them."""
    handler: dict[str, list[int]] = {}
    send: dict[str, list[int]] = {}
    for row in conn.execute(TIMED_SQL, scope.params()):
        command = str(row["command"])
        handler.setdefault(command, []).append(int(row["handler_ms"]))
        if row["send_ms"] is not None:
            send.setdefault(command, []).append(int(row["send_ms"]))
    upstream: dict[str, list[int]] = {}
    for row in conn.execute(COMMAND_UPSTREAM_SQL, scope.params()):
        upstream.setdefault(str(row["command"]), []).append(int(row["duration_ms"]))
    for values in (*handler.values(), *send.values(), *upstream.values()):
        values.sort()
    return sorted(
        (
            Latency(
                command=command,
                samples=len(values),
                handler_p50=percentile(values, P50),
                handler_p95=percentile(values, P95),
                send_p50=percentile(send.get(command, []), P50),
                upstream_p50=percentile(upstream.get(command, []), P50),
            )
            for command, values in handler.items()
        ),
        key=lambda entry: (-entry.handler_p50, entry.command),
    )


def gates(conn: sqlite3.Connection, scope: Scope) -> list[tuple[str, str, int]]:
    """(command, which gate, how often). A high count is mis-tuning."""
    return [
        (str(row["command"]), str(row["outcome"]), int(row["n"]))
        for row in conn.execute(GATES_SQL, scope.params())
    ]


def errors(conn: sqlite3.Connection, scope: Scope) -> list[tuple[str, str, int]]:
    """(command, exception class, how often). Never an exception message."""
    return [
        (str(row["command"]), str(row["error_class"]), int(row["n"]))
        for row in conn.execute(ERRORS_SQL, scope.params())
    ]


def upstreams(conn: sqlite3.Connection, scope: Scope) -> list[Upstream]:
    """Every external service the bot depends on, and how it is holding up."""
    times: dict[str, list[int]] = {}
    for row in conn.execute(UPSTREAM_TIMES_SQL, scope.params()):
        times.setdefault(str(row["host"]), []).append(int(row["duration_ms"]))
    for values in times.values():
        values.sort()
    return [
        Upstream(
            host=str(row["host"]),
            calls=int(row["calls"]),
            failures=int(row["failures"] or 0),
            p50_ms=percentile(times.get(str(row["host"]), []), P50),
        )
        for row in conn.execute(UPSTREAM_SQL, scope.params())
    ]