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.

8.1 KB
Raw Blame
"""Format alert-breach values and breakdown labels the way the insight itself displays them.

This is a backend port of the frontend `formatAggregationAxisValue`
(`frontend/src/lib/insights/aggregationAxisFormat.ts`): given a trends insight's axis config
(`aggregationAxisFormat`, prefix/postfix, decimal places) plus the team's base currency, render a
raw metric value as the user sees it on the chart — so notification messages read "($803.77)" and
"(Other (i.e. all remaining values))" instead of "(803.7740196999998)" and a raw breakdown sentinel.
"""

import math
from collections.abc import Callable

from posthog.schema import AggregationAxisFormat, TrendsFilter

from posthog.utils import compact_number

DEFAULT_DECIMAL_PLACES = 2

# en-US currency symbols for common currencies, mirroring the Intl.NumberFormat('en-US') output the
# frontend's formatCurrency relies on. Unlisted currencies fall back to a "<CODE> " prefix, and a
# missing currency falls back to "$" (matching the frontend humanFriendlyCurrency fallback).
_CURRENCY_SYMBOLS: dict[str, str] = {
    "USD": "$",
    "EUR": "€",
    "GBP": "£",
    "JPY": "¥",
    "CNY": "CN¥",
    "INR": "₹",
    "KRW": "₩",
    "RUB": "₽",
    "BRL": "R$",
    "CAD": "CA$",
    "AUD": "A$",
    "NZD": "NZ$",
    "HKD": "HK$",
    "SGD": "S$",
    "MXN": "MX$",
    "TRY": "₺",
    "THB": "฿",
    "PHP": "₱",
    "IDR": "Rp",
    "ILS": "₪",
    "ZAR": "R",
    "CHF": "CHF ",
    "SEK": "SEK ",
    "NOK": "NOK ",
    "DKK": "DKK ",
    "PLN": "PLN ",
    "AED": "AED ",
    "SAR": "SAR ",
}


def make_trends_value_formatter(trends_filter: TrendsFilter | None, currency: str | None) -> Callable[[float], str]:
    """Bind a trends insight's axis config into a one-arg value formatter for the comparator.

    Tolerates ``trends_filter=None`` (a valid trends query state) by rendering a plain humanized number.
    """
    axis_format = trends_filter.aggregationAxisFormat if trends_filter else None
    prefix = trends_filter.aggregationAxisPrefix if trends_filter else None
    postfix = trends_filter.aggregationAxisPostfix if trends_filter else None
    decimal_places = trends_filter.decimalPlaces if trends_filter else None
    min_decimal_places = trends_filter.minDecimalPlaces if trends_filter else None

    def _format(value: float) -> str:
        return format_aggregation_value(
            value,
            axis_format=axis_format,
            prefix=prefix,
            postfix=postfix,
            decimal_places=decimal_places,
            min_decimal_places=min_decimal_places,
            currency=currency,
        )

    return _format


def format_aggregation_value(
    value: float,
    *,
    axis_format: AggregationAxisFormat | None = None,
    prefix: str | None = None,
    postfix: str | None = None,
    decimal_places: float | None = None,
    min_decimal_places: float | None = None,
    currency: str | None = None,
) -> str:
    """Render a single metric value per the insight's axis format, wrapped in its prefix/postfix."""
    if not math.isfinite(value):
        formatted = "∞" if value > 0 else "-∞" if value < 0 else "NaN"
        return f"{prefix or ''}{formatted}{postfix or ''}"

    match axis_format:
        case AggregationAxisFormat.DURATION:
            formatted = _format_duration_seconds(value)
        case AggregationAxisFormat.DURATION_MS:
            formatted = _format_duration_seconds(value / 1000, seconds_fixed=1)
        case AggregationAxisFormat.DURATION_NS:
            formatted = _format_duration_nanoseconds(value)
        case AggregationAxisFormat.PERCENTAGE:
            formatted = _percentage(value / 100, decimal_places)
        case AggregationAxisFormat.PERCENTAGE_SCALED:
            formatted = _percentage(value, decimal_places)
        case AggregationAxisFormat.CURRENCY:
            formatted = _format_currency(value, currency)
        case AggregationAxisFormat.SHORT:
            formatted = compact_number(value)
        case _:  # NUMERIC or unset
            formatted = _human_friendly_number(value, decimal_places, min_decimal_places)

    # Currency format already embeds the symbol, so a matching prefix ("$" + "$94.02") would double it.
    effective_prefix = (
        ""
        if (axis_format == AggregationAxisFormat.CURRENCY and prefix and formatted.startswith(prefix))
        else (prefix or "")
    )
    return f"{effective_prefix}{formatted}{postfix or ''}"


def _clamp_decimal_places(value: float | None, fallback: int) -> int:
    """Mirror the frontend validateFractionDigits: only accept a whole number in [0, 100]."""
    if value is None:
        return fallback
    as_int = int(value)
    if as_int != value or as_int < 0 or as_int > 100:
        return fallback
    return as_int


def _human_friendly_number(
    value: float, max_decimal_places: float | None = None, min_decimal_places: float | None = None
) -> str:
    """Thousands-separated number, trimming trailing zeros down to min_decimal_places.

    Port of the frontend humanFriendlyNumber (`(n).toLocaleString('en-US', {...})`).
    """
    max_dp = _clamp_decimal_places(max_decimal_places, DEFAULT_DECIMAL_PLACES)
    min_dp = _clamp_decimal_places(min_decimal_places, 0)
    if min_dp > max_dp:
        min_dp = max_dp

    formatted = f"{value:,.{max_dp}f}"
    if "." not in formatted:
        return formatted
    integer_part, _, frac = formatted.partition(".")
    frac = frac.rstrip("0")
    if len(frac) < min_dp:
        frac = frac.ljust(min_dp, "0")
    return f"{integer_part}.{frac}" if frac else integer_part


def _percentage(division: float, max_decimal_places: float | None = None) -> str:
    """Render a fraction as a percentage, e.g. 0.5 -> "50%" (port of the frontend percentage())."""
    if not math.isfinite(division):
        return "∞%" if division > 0 else "-∞%" if division < 0 else "NaN%"
    return f"{_human_friendly_number(division * 100, max_decimal_places, 0)}%"


def _format_currency(value: float, currency: str | None) -> str:
    """Prefix the humanized number (fixed 2 decimals, like the frontend formatCurrency) with the
    currency symbol. Unknown currencies fall back to the code; a missing currency falls back to "$"."""
    number = _human_friendly_number(value, DEFAULT_DECIMAL_PLACES, DEFAULT_DECIMAL_PLACES)
    if not currency:
        return f"${number}"
    symbol = _CURRENCY_SYMBOLS.get(currency.upper())
    if symbol is not None:
        return f"{symbol}{number}"
    return f"{currency.upper()} {number}"


def _format_duration_seconds(value: float, *, seconds_fixed: int | None = None) -> str:
    """Convert seconds to a human-readable duration ("45s", "2m 12s", "1h 4m", "850ms").

    Port of the frontend humanFriendlyDuration; handles negative (relative differences) and zero.
    """
    if value < 0:
        return f"-{_format_duration_seconds(-value, seconds_fixed=seconds_fixed)}"
    if value == 0:
        return "0s"
    if value < 1:
        return f"{round(value * 1000)}ms"
    if value < 60:
        return f"{_trim_float(f'{value:.{seconds_fixed or 0}f}')}s"

    days = math.floor(value / 86400)
    hours = math.floor((value % 86400) / 3600)
    minutes = math.floor((value % 3600) / 60)
    seconds = math.floor((value % 3600) % 60)

    day_display = f"{days}d" if days > 0 else ""
    hour_display = f"{hours}h" if hours > 0 else ""
    minute_display = f"{minutes}m" if minutes > 0 else ""
    second_display = f"{seconds}s" if seconds > 0 else ("" if (hour_display or minute_display) else "0s")

    if days > 0:
        units = [u for u in (day_display, hour_display) if u]
    else:
        units = [u for u in (hour_display, minute_display, second_display) if u]
    return " ".join(units)


def _format_duration_nanoseconds(value: float) -> str:
    absolute_value = abs(value)
    if absolute_value < 1_000:
        return f"{_human_friendly_number(value)}ns"
    if absolute_value < 1_000_000:
        return f"{_human_friendly_number(value / 1_000)}µs"
    return _format_duration_seconds(value / 1_000_000_000, seconds_fixed=1)


def _trim_float(formatted: str) -> str:
    """Strip trailing zeros (and a bare trailing dot) from a fixed-point string, like JS parseFloat."""
    if "." in formatted:
        formatted = formatted.rstrip("0").rstrip(".")
    return formatted