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.

5.9 KB
Raw Blame
from dataclasses import replace
from datetime import date, datetime, timedelta
from zoneinfo import ZoneInfo

from posthog.schema import ChartDisplayType, IntervalType, NodeKind, TrendsQuery

from posthog.tasks.alerts.trends import _has_breakdown, _is_non_time_series_trend
from posthog.tasks.alerts.utils import WRAPPER_NODE_KINDS, AlertEvaluationResult
from posthog.utils import get_from_dict_or_attr

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


class DelayedEvaluationUnavailable(Exception):
    pass


def validate_evaluation_delay(query: object, config: object, delay: int) -> None:
    if isinstance(delay, bool) or not isinstance(delay, int) or not 0 <= delay <= 100:
        raise ValueError("Evaluation delay must be a whole number between 0 and 100 intervals.")
    if delay == 0:
        return
    if get_from_dict_or_attr(query, "kind") in WRAPPER_NODE_KINDS:
        query = get_from_dict_or_attr(query, "source")
    if get_from_dict_or_attr(query, "kind") != NodeKind.TRENDS_QUERY:
        raise ValueError("Evaluation delay is only supported for time-series Trends insights.")
    trends_query = TrendsQuery.model_validate(query)
    display = trends_query.trendsFilter.display if trends_query.trendsFilter else None
    # The Trends runner returns a calendar heatmap as one aggregated value, not interval points.
    if _is_non_time_series_trend(trends_query) or display == ChartDisplayType.CALENDAR_HEATMAP:
        raise ValueError("Evaluation delay is only supported for time-series Trends insights.")
    # Compare mode adds previous-period breakdown rows with their own dates, and the check cannot
    # tell which row breached, so it cannot name the evaluated interval.
    if _has_breakdown(trends_query) and trends_query.compareFilter and trends_query.compareFilter.compare:
        raise ValueError(
            "Evaluation delay is not supported for breakdown insights that compare to a previous period. "
            "Turn off the comparison or set the delay to 0."
        )
    # A daysOfWeek filter drops day buckets, so a calendar-day lookback returns too few intervals.
    days_of_week = trends_query.dateRange.daysOfWeek if trends_query.dateRange else None
    if (trends_query.interval or IntervalType.DAY) == IntervalType.DAY and days_of_week and len(set(days_of_week)) < 7:
        raise ValueError(
            "Evaluation delay is not supported for daily insights that filter days of the week. "
            "Include every day or set the delay to 0."
        )
    if config is not None and not isinstance(config, dict):
        raise ValueError("Alert config must be a JSON object.")
    if (config or {}).get("check_ongoing_interval"):
        raise ValueError("Turn off Check ongoing period to use an evaluation delay.")


def apply_evaluation_delay(
    result: ExtractionResult, *, delay: int, minimum_points: int, timezone: str
) -> ExtractionResult:
    if delay == 0:
        return result
    selected_series = []
    evaluated_interval = None
    for series in result.series:
        index = series.current_index - delay
        if index + 1 < minimum_points:
            raise DelayedEvaluationUnavailable(
                f"Not enough completed intervals after the evaluation delay. At least {minimum_points} eligible "
                "intervals are required. Wait for more data or reduce the evaluation delay."
            )
        if any(point.value is None for point in series.points[index + 1 - minimum_points : index + 1]):
            raise DelayedEvaluationUnavailable(
                "The eligible intervals contain missing values. Wait for more data or check the insight."
            )
        start, end = series.points[index].date, series.points[index + 1].date
        if start is None or end is None:
            raise DelayedEvaluationUnavailable("The delayed interval has no dates. Check the insight and try again.")
        if result.interval_type == IntervalType.DAY:
            end = _day_bucket_end(start, end, timezone)
        evaluated_interval = EvaluatedInterval(start=start, end=end, timezone=timezone, delay=delay)
        selected_series.append(replace(series, points=series.points[: index + 1], current_index=index))
    if not selected_series:
        raise DelayedEvaluationUnavailable(
            "No completed intervals are available after the evaluation delay. Wait for more data or reduce the delay."
        )
    return replace(
        result, series=selected_series, evaluated_interval=evaluated_interval, framed=False, include_series_label=True
    )


def _day_bucket_end(start: str, next_start: str, timezone: str) -> str:
    # A daysOfWeek filter drops day buckets, so the next returned bucket can start days later.
    try:
        if date.fromisoformat(next_start[:10]) - date.fromisoformat(start[:10]) <= timedelta(days=1):
            return next_start
        if len(start) == 10:
            return (date.fromisoformat(start) + timedelta(days=1)).isoformat()
        moment = datetime.fromisoformat(start)
    except ValueError:
        return next_start
    if moment.tzinfo is not None:
        moment = moment.astimezone(ZoneInfo(timezone))
    return (moment + timedelta(days=1)).isoformat()


def describe_delayed_evaluation(result: AlertEvaluationResult, extraction: ExtractionResult) -> AlertEvaluationResult:
    interval = extraction.evaluated_interval
    if interval is None:
        return result
    context = f"Evaluated {interval.start} to {interval.end} ({interval.timezone}; delay: {interval.delay} intervals)."
    return replace(
        result,
        breaches=[f"{context} {breach}" for breach in result.breaches] if result.breaches else result.breaches,
        triggered_metadata={
            **(result.triggered_metadata or {}),
            "evaluation_delay_intervals": interval.delay,
            "evaluated_interval_start": interval.start,
            "evaluated_interval_end": interval.end,
            "evaluated_interval_timezone": interval.timezone,
        },
    )