Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

10.0 KB
Raw Blame
from collections.abc import Callable

from posthog.schema import (
    AlertCondition,
    AlertConditionType,
    InsightsThresholdBounds,
    InsightThreshold,
    InsightThresholdType,
    IntervalType,
)

from posthog.tasks.alerts.utils import AlertEvaluationResult

from products.alerts.backend.evaluation.contract import ComparableSeries, ExtractionResult

# Aggregated (any-row) breach lists are capped so a wide violation doesn't flood the notification.
# The persisted structured detail uses the same cap.
MAX_BREACH_MESSAGES = 5


def _breach_messages(
    bounds: InsightsThresholdBounds,
    calculated_value: float,
    threshold_type: InsightThresholdType,
    condition_type: AlertConditionType,
    *,
    subject: str,
    framed: bool,
    include_series: bool = False,
    interval_type: IntervalType | None = None,
    series: str | None = None,
    is_current_interval: bool = False,
    unit: str = "",
    value_formatter: Callable[[float], str] | None = None,
) -> list[str]:
    is_percentage = threshold_type == InsightThresholdType.PERCENTAGE

    # PERCENTAGE thresholds render the relative-change ratio as their own % and take precedence.
    # Otherwise a trends ``value_formatter`` mirrors the insight's axis format (currency, prefix,
    # decimals). Falls back to raw value + ``unit`` (e.g. "%" for funnel conversion rates, which are
    # absolute 0–100 values) to keep the notification consistent with the configure-time UI.
    def _fmt(value: float) -> str:
        if is_percentage:
            return f"{value:.2%}"
        if value_formatter is not None:
            return value_formatter(value)
        return f"{value}{unit}"

    formatted_value = _fmt(calculated_value)

    match condition_type:
        case AlertConditionType.ABSOLUTE_VALUE:
            condition_text = "is"
        case AlertConditionType.RELATIVE_INCREASE:
            condition_text = "increased"
        case AlertConditionType.RELATIVE_DECREASE:
            condition_text = "decreased"
        case _:
            raise ValueError(f"Unsupported alert condition type: {condition_type}")

    # Framed (time-series trends): "(label) for current/previous interval". Unframed (e.g. SQL
    # insights): just the subject — plus the series label when several series are in play
    # (any-row SQL alerts), since the reader needs to know which row breached.
    if framed:
        context = f" ({series}) for {'current' if is_current_interval else 'previous'} {interval_type or 'interval'}"
    elif include_series and series is not None:
        context = f" ({series})"
    else:
        context = ""

    if bounds.lower is not None and calculated_value < bounds.lower:
        return [
            f"{subject}{context} ({formatted_value}) {condition_text} less than lower threshold ({_fmt(bounds.lower)})"
        ]

    if bounds.upper is not None and calculated_value > bounds.upper:
        return [
            f"{subject}{context} ({formatted_value}) {condition_text} more than upper threshold ({_fmt(bounds.upper)})"
        ]

    return []


def _relative_value(
    condition_type: AlertConditionType,
    threshold_type: InsightThresholdType,
    anchor: float,
    previous: float,
) -> float:
    """Compute the relative change between the anchor point and the one before it.

    Both increase and decrease divide by ``previous`` (the earlier interval); the sign of
    the numerator flips so a decrease is reported as a positive magnitude.
    """
    numerator = anchor - previous if condition_type == AlertConditionType.RELATIVE_INCREASE else previous - anchor

    if threshold_type == InsightThresholdType.ABSOLUTE:
        return numerator
    if threshold_type != InsightThresholdType.PERCENTAGE:
        raise ValueError(f"Neither relative nor absolute threshold configured for alert condition {condition_type}")
    if previous == 0 and anchor == 0:
        return 0
    if previous == 0:
        return float("inf")
    return numerator / previous


def _breach_detail(
    result: ExtractionResult,
    series: ComparableSeries,
    condition: AlertCondition,
    threshold: InsightThreshold,
    calculated: float,
) -> dict[str, str]:
    def format_value(value: float, *, change: bool = False) -> str:
        if change and threshold.type == InsightThresholdType.PERCENTAGE:
            return f"{value:.2%}"
        if result.value_formatter is not None:
            return result.value_formatter(value)
        return f"{value:g}{result.unit}"

    current = series.points[series.current_index]
    previous = series.points[series.current_index - 1] if series.current_index > 0 else None
    detail = {"observed": format_value(current.value if current.value is not None else calculated)}
    if result.framed or result.is_breakdown or result.include_series_label:
        detail["group"] = series.label[:400]
    if current.date:
        detail["date"] = current.date
    if result.interval_type:
        detail["interval"] = result.interval_type
    relative = condition.type != AlertConditionType.ABSOLUTE_VALUE
    if previous is not None and previous.value is not None:
        detail["previous"] = format_value(previous.value)
        detail["previous_label"] = "Previous interval"
        if relative:
            if previous.value == 0 and threshold.type == InsightThresholdType.PERCENTAGE:
                detail["change"] = "Not defined from zero"
            else:
                arrow = "▲" if current.value is not None and current.value > previous.value else "▼"
                detail["change"] = f"{arrow} {format_value(abs(calculated), change=True)}"
    if threshold.bounds is not None:
        for side, bound in (("lower", threshold.bounds.lower), ("upper", threshold.bounds.upper)):
            if bound is not None and (
                (side == "lower" and calculated < bound) or (side == "upper" and calculated > bound)
            ):
                detail["limit_label"] = "Change limit" if relative else f"{side.capitalize()} limit"
                detail["limit"] = format_value(bound, change=relative)
                break
    return detail


def evaluate_threshold(
    result: ExtractionResult,
    condition: AlertCondition,
    threshold: InsightThreshold | None,
) -> AlertEvaluationResult:
    """Compare an extractor's result against the threshold; breach if ANY series breaches.

    Kind-agnostic: every insight kind's extractor normalizes into an ``ExtractionResult`` and the
    completeness/ongoing-interval policy is already encoded in each series' ``current_index``.

    ``result.is_breakdown`` controls only the no-breach reported value: a breakdown query has no
    single representative value, so it reports ``None``, whereas a single-series query reports its
    computed value.
    """
    bounds = threshold.bounds if threshold else None
    if not threshold or not bounds:
        return AlertEvaluationResult(value=0, breaches=[])

    calculated: float | None = None
    all_breaches: list[str] = []
    breaching_rows: list[dict] = []
    breach_details: list[dict[str, str]] = []
    first_breach_value: float | None = None
    for s in result.series:
        anchor = s.points[s.current_index].value
        if anchor is None:
            continue

        if condition.type == AlertConditionType.ABSOLUTE_VALUE:
            calculated = anchor
        else:
            previous = s.points[s.current_index - 1].value if s.current_index - 1 >= 0 else None
            if previous is None:
                continue
            calculated = _relative_value(condition.type, threshold.type, anchor, previous)

        breaches = _breach_messages(
            bounds,
            calculated,
            threshold.type,
            condition.type,
            subject=result.subject,
            framed=result.framed,
            include_series=result.is_breakdown or result.include_series_label,
            interval_type=result.interval_type,
            series=s.label,
            is_current_interval=s.is_current_interval,
            unit=result.unit,
            value_formatter=result.value_formatter,
        )
        if breaches:
            detail = _breach_detail(result, s, condition, threshold, calculated)
            if not result.aggregate_breaches:
                return AlertEvaluationResult(
                    value=calculated, breaches=breaches, triggered_metadata={"breach_details": [detail]}
                )
            if len(breach_details) < MAX_BREACH_MESSAGES:
                breach_details.append(detail)
            if first_breach_value is None:
                # Representative value = the first breaching row in result order; the full list
                # of breaching rows is carried by ``breaches`` and ``triggered_metadata``.
                first_breach_value = calculated
            all_breaches.extend(breaches)
            breaching_rows.append({"label": s.label, "value": calculated})

    if all_breaches:
        capped = all_breaches[:MAX_BREACH_MESSAGES]
        if len(all_breaches) > MAX_BREACH_MESSAGES:
            breach_details[-1]["other_groups"] = str(len(breaching_rows) - MAX_BREACH_MESSAGES)
            capped.append(f"...and {len(all_breaches) - MAX_BREACH_MESSAGES} more rows breach")
        # Persist which rows breached on the check record — notifications are transient, and the
        # row labels have no other durable source of truth.
        return AlertEvaluationResult(
            value=first_breach_value,
            breaches=capped,
            triggered_metadata={
                "breaching_rows": breaching_rows[:MAX_BREACH_MESSAGES],
                "breach_details": breach_details,
                "breaching_row_count": len(breaching_rows),
            },
        )

    # No breach: an empty query result reports 0 regardless of breakdown (the metric is genuinely
    # zero — matching the original _is_empty_query_result); otherwise a non-breakdown query reports
    # its computed value and a breakdown has no single representative value, so it reports None.
    if result.empty_query_result:
        no_breach_value: float | None = 0
    else:
        no_breach_value = None if result.is_breakdown else calculated
    return AlertEvaluationResult(value=no_breach_value, breaches=[])