Defining Freshness SLOs for Tile Layers

from __future__ import annotations

from dataclasses import dataclass

import psycopg
from prometheus_client import Gauge

FRESHNESS_SLI = Gauge("tile_freshness_sli", "Weighted share within the age target",
                      ("layer",))
FRESHNESS_TARGET = Gauge("tile_freshness_target", "The objective, for the dashboard",
                         ("layer",))


@dataclass(frozen=True)
class FreshnessObjective:
    layer: str
    max_age_hours: float      # from the phenomenon, not from the pipeline
    target: float             # weighted share that must comply
    window_days: int = 30

    @property
    def budget_hours(self) -> float:
        """How much non-compliance the window permits, as a wall-clock figure."""
        return (1.0 - self.target) * self.window_days * 24


OBJECTIVES = [
    # A flood extent is useless at four hours old; imagery is fine at a month.
    FreshnessObjective("flood_extent", max_age_hours=2, target=0.99),
    FreshnessObjective("traffic", max_age_hours=0.25, target=0.98),
    FreshnessObjective("roads", max_age_hours=24 * 7, target=0.99),
    FreshnessObjective("ortho", max_age_hours=24 * 30, target=0.95),
]


SLI_SQL = """
SELECT
  sum(weight) FILTER (
      WHERE built_at > now() - (%(max_age_hours)s * interval '1 hour')
  ) / NULLIF(sum(weight), 0)                       AS sli,
  -- Reported alongside, because it is what a human wants to see next.
  max(EXTRACT(EPOCH FROM now() - built_at)) / 3600 AS oldest_hours
FROM   tile_ledger
WHERE  layer = %(layer)s AND in_serving_area
"""


def publish_freshness(conn: psycopg.Connection) -> None:
    for obj in OBJECTIVES:
        with conn.cursor() as cur:
            cur.execute(SLI_SQL, {"layer": obj.layer, "max_age_hours": obj.max_age_hours})
            sli, oldest = cur.fetchone()
        FRESHNESS_SLI.labels(layer=obj.layer).set(float(sli or 0.0))
        FRESHNESS_TARGET.labels(layer=obj.layer).set(obj.target)

groups:
  - name: freshness-slo
    rules:
      # The SLI is computed once and reused, so both rules agree by construction.
      - record: slo:freshness_error_ratio
        expr: 1 - tile_freshness_sli

      # Fast burn: at this rate the month's budget is gone in about two days.
      - alert: FreshnessBudgetBurningFast
        expr: |
          slo:freshness_error_ratio
            > 14.4 * (1 - tile_freshness_target)
        for: 15m
        labels: { severity: page }
        annotations:
          summary: "{{ $labels.layer }} freshness budget burning at 14x — 2 days to exhaustion"

      # Slow burn: not urgent, and this is how a month's budget disappears unnoticed.
      - alert: FreshnessBudgetEroding
        expr: |
          slo:freshness_error_ratio
            > 3 * (1 - tile_freshness_target)
        for: 6h
        labels: { severity: ticket }
        annotations:
          summary: "{{ $labels.layer }} freshness budget eroding at 3x for six hours"

def test_budget_hours_arithmetic() -> None:
    obj = FreshnessObjective("ortho", max_age_hours=720, target=0.95, window_days=30)
    # 5% of 720 hours in the window = 36 hours of permitted non-compliance.
    assert obj.budget_hours == pytest.approx(36.0)


def test_sli_is_weighted_not_counted(conn, seeded_ledger) -> None:
    """One stale city must cost more than a thousand stale ocean tiles."""
    make_stale(conn, layer="ortho", region="oslo")
    weighted = compute_sli(conn, OBJECTIVES[3])

    reset(conn)
    make_stale(conn, layer="ortho", region="north_sea", tiles=1000)
    ocean = compute_sli(conn, OBJECTIVES[3])

    assert weighted < ocean, "the weighting is not being applied"


def test_boundary_is_inclusive_and_consistent(conn) -> None:
    """A tile exactly at the age limit must be treated the same way every run."""
    insert_tile(conn, layer="ortho", age_hours=720.0)
    first = compute_sli(conn, OBJECTIVES[3])
    second = compute_sli(conn, OBJECTIVES[3])
    assert first == second


def test_empty_serving_area_does_not_divide_by_zero(conn) -> None:
    assert compute_sli(conn, FreshnessObjective("empty_layer", 24, 0.99)) == 0.0

SELECT l.layer,
       round(100 * l.sli::numeric, 2)            AS sli_pct,
       round(100 * o.target::numeric, 2)         AS target_pct,
       round(l.oldest_hours::numeric, 1)         AS oldest_hours,
       round((1 - (1 - l.sli) / (1 - o.target))::numeric, 3) AS budget_remaining
FROM   freshness_sli l
JOIN   freshness_objective o USING (layer)
ORDER  BY budget_remaining;