Percentile Aggregation für belastbare Performance-Metriken

1. Warum ein Durchschnitt Latenzspitzen verbirgt

Ein arithmetischer Durchschnitt fasst eine Verteilung von Werten in einer einzigen Zahl zusammen, verliert dabei aber genau die Information, die für Performance-Monitoring am wichtigsten ist: wie sich die Ausreißer verhalten. Bei 999 Requests mit 50 Millisekunden Antwortzeit und einem einzigen Request mit 5 Sekunden liegt der Durchschnitt bei etwa 55 Millisekunden, ein Wert, der die katastrophale Erfahrung des einen betroffenen Nutzers komplett verschluckt. Eine Percentile Aggregation macht diesen Ausreißer sichtbar, weil sie nicht einen einzigen Mittelwert, sondern mehrere Punkte der tatsächlichen Verteilung berechnet.

Der Grund, warum das für Web-Shops und APIs praktisch relevant ist: Nutzer erinnern sich an ihre langsamsten Erlebnisse, nicht an den statistischen Durchschnitt. Wenn 5 Prozent der Checkout-Requests eine Antwortzeit über 3 Sekunden haben, bedeutet das bei zehntausend täglichen Bestellungen fünfhundert frustrierte Kunden, selbst wenn der Durchschnitt komfortabel bei 200 Millisekunden liegt. Eine Percentile Aggregation mit p95 oder p99 macht genau dieses Problem quantifizierbar, während ein reiner avg-Wert es systematisch versteckt.

Die folgenden Abschnitte erklären die percentiles Aggregation von der Grundsyntax über den TDigest-Algorithmus bis zu vollständigen Latenz-Dashboards mit mehreren Perzentil-Stufen. Jedes Beispiel nutzt reale Aggregations-Syntax, wie sie gegen Logging- oder APM-Indizes in Elasticsearch läuft.

2. Grundlagen: die percentiles Aggregation

Die percentiles Aggregation berechnet standardmäßig sieben Perzentile eines numerischen Felds: 1, 5, 25, 50, 75, 95 und 99. Jedes Perzentil gibt den Wert an, unter dem ein bestimmter Prozentsatz aller Datenpunkte liegt. p50, das mediane Perzentil, entspricht dem klassischen Median: die Hälfte aller Requests ist schneller, die Hälfte langsamer als dieser Wert. Für die meisten Performance-Analysen sind p50, p95 und p99 die relevantesten Kennzahlen einer Percentile Aggregation, weshalb sie meist explizit über den percents-Parameter angefordert werden, statt sich auf die Standardauswahl zu verlassen.

Die Query-Syntax ähnelt anderen Metrik-Aggregationen: field gibt das numerische Feld an, dessen Verteilung analysiert werden soll, percents eine Liste der gewünschten Perzentil-Werte. Für Latenzdaten ist response_time_ms in Millisekunden ein typisches Zielfeld, das aus Access-Logs oder APM-Traces stammt.

GET /api-logs/_search
{
  "size": 0,
  "query": {
    "range": { "@timestamp": { "gte": "now-1h" } }
  },
  "aggs": {
    "response_time_percentiles": {
      "percentiles": {
        "field": "response_time_ms",
        "percents": [50, 75, 90, 95, 99, 99.9]
      }
    }
  }
}

3. Wie TDigest Perzentile approximiert

Eine exakte Perzentil-Berechnung würde erfordern, alle Werte zu sortieren und den Wert an der entsprechenden Position auszulesen, was bei Millionen oder Milliarden Dokumenten weder speicher- noch zeiteffizient ist. Die percentiles Aggregation in Elasticsearch nutzt deshalb standardmäßig den TDigest-Algorithmus, eine probabilistische Datenstruktur, die eine kompakte Zusammenfassung der Verteilung im Arbeitsspeicher hält, statt jeden Einzelwert zu behalten. Diese Percentile Aggregation-Struktur liefert damit approximierte statt exakte Werte, mit einer Genauigkeit, die für praktisch alle Monitoring-Zwecke ausreicht.

Die Besonderheit von TDigest ist, dass die Genauigkeit an den Rändern der Verteilung, also bei sehr niedrigen und sehr hohen Perzentilen wie p1 oder p99.9, höher ist als in der Mitte bei p50. Das ist kein Zufall, sondern bewusstes Design: Für Latenz-Monitoring sind gerade die extremen Perzentile am wichtigsten, weil sie die Nutzer mit der schlechtesten Erfahrung repräsentieren, während eine ungenauere Approximation im mittleren Bereich in der Praxis kaum ins Gewicht fällt.

4. p50, p95 und p99 richtig interpretieren

p50 entspricht dem Median und beschreibt die typische Erfahrung eines durchschnittlichen Nutzers. Für die meisten Performance-Ziele ist p50 allein aber unzureichend, weil es per Definition die Hälfte aller Requests ignoriert. p95 sagt aus, dass 95 Prozent aller Requests schneller sind als dieser Wert, während die restlichen 5 Prozent langsamer sind. Für einen Shop mit hohem Traffic bedeutet ein p95 von 2 Sekunden, dass jeder zwanzigste Request diese Schwelle überschreitet, ein Anteil, der bei hohem Volumen absolut betrachtet viele betroffene Nutzer bedeutet.

p99 verschärft diese Betrachtung weiter und ist besonders relevant für Systeme mit strengen Latenz-Anforderungen, etwa Zahlungsabwicklung oder Echtzeit-Suche. Eine Percentile Aggregation mit p99 zeigt die Antwortzeit, die von den langsamsten 1 Prozent aller Requests überschritten wird. Der Abstand zwischen p50 und p99 ist dabei oft aussagekräftiger als jeder einzelne Wert für sich: Ein System mit p50 bei 100 Millisekunden und p99 bei 150 Millisekunden verhält sich fundamental anders als eines mit p50 bei 100 Millisekunden und p99 bei 8 Sekunden, obwohl der Median in beiden Fällen identisch aussieht.

GET /api-logs/_search
{
  "size": 0,
  "query": {
    "bool": {
      "filter": [
        { "term": { "endpoint": "/checkout" } },
        { "range": { "@timestamp": { "gte": "now-24h" } } }
      ]
    }
  },
  "aggs": {
    "checkout_latency": {
      "percentiles": {
        "field": "response_time_ms",
        "percents": [50, 95, 99]
      }
    }
  }
}

5. percentile_ranks: SLA-Erfüllung messen

Während percentiles eine Perzentil-Angabe in einen konkreten Wert übersetzt, funktioniert percentile_ranks genau umgekehrt: Sie übersetzt einen konkreten Schwellwert in den Prozentsatz der Requests, die diesen Wert unterschreiten. Für ein SLA, das eine Antwortzeit unter 500 Millisekunden verspricht, beantwortet diese Percentile Aggregation-Variante direkt die Frage "wie viel Prozent aller Requests erfüllen dieses Ziel", ohne dass man erst eine Reihe von Perzentilen durchprobieren muss.

percentile_ranks eignet sich damit ideal für SLA-Dashboards und Alerting-Regeln, die eine feste Erfüllungsquote überwachen sollen, etwa "99 Prozent aller Requests unter 1 Sekunde". Ein Alert, der auslöst, sobald der von percentile_ranks gelieferte Wert unter 99 fällt, ist direkter und aussagekräftiger als ein Alert auf einen einzelnen Perzentil-Wert, weil er die tatsächliche Zielverfehlung in Prozentpunkten ausdrückt.

GET /api-logs/_search
{
  "size": 0,
  "aggs": {
    "sla_compliance": {
      "percentile_ranks": {
        "field": "response_time_ms",
        "values": [500, 1000, 3000]
      }
    }
  }
}

6. Percentile Aggregation über Zeiträume hinweg

Für Monitoring-Dashboards wird eine Percentile Aggregation meist als Sub-Aggregation unter ein date_histogram gehängt, um zu sehen, wie sich p95 und p99 über die Zeit verändern. Diese Kombination zeigt Latenz-Trends, die ein einzelner Gesamtwert nicht sichtbar machen würde, etwa eine schrittweise Verschlechterung der Antwortzeiten über mehrere Tage oder plötzliche Latenzspitzen zu bestimmten Uhrzeiten mit hoher Last.

Eine wichtige Einschränkung: TDigest-Zustände lassen sich zwischen Buckets eines date_histogram nicht sinnvoll mitteln oder direkt vergleichen, weil jede Bucket-Berechnung ihre eigene, unabhängige TDigest-Struktur aufbaut. Ein globaler p99 über einen Monat ist deshalb nicht identisch mit dem Durchschnitt der täglichen p99-Werte, da sich beide Berechnungen auf unterschiedliche Datenmengen und Verteilungen beziehen. Für belastbare Monats- oder Quartalsauswertungen empfiehlt sich immer eine separate Percentile Aggregation über den gesamten Zeitraum, nicht die nachträgliche Mittelung von Tageswerten.

GET /api-logs/_search
{
  "size": 0,
  "query": {
    "range": { "@timestamp": { "gte": "now-7d" } }
  },
  "aggs": {
    "latency_per_hour": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "hour",
        "min_doc_count": 0
      },
      "aggs": {
        "p95_p99": {
          "percentiles": {
            "field": "response_time_ms",
            "percents": [95, 99]
          }
        }
      }
    }
  }
}

7. Genauigkeit steuern: compression und hdr

Der Parameter compression steuert die Genauigkeit der TDigest-basierten Percentile Aggregation, indem er festlegt, wie viele interne Knoten die Datenstruktur verwendet. Ein höherer compression-Wert erhöht die Genauigkeit auf Kosten von mehr Speicherverbrauch, ein niedrigerer Wert spart Speicher zulasten der Präzision. Der Standardwert von 100 ist für die meisten Anwendungsfälle ausreichend genau, für Monitoring-Systeme mit strengen Anforderungen an extreme Perzentile kann eine Erhöhung sinnvoll sein.

Als Alternative zu TDigest bietet Elasticsearch den HDR-Histogram-Algorithmus, aktivierbar über den Parameter method. HDR arbeitet mit fester statt adaptiver Genauigkeit und eignet sich besonders für Werte mit bekanntem, begrenztem Wertebereich, etwa Latenzen zwischen 0 und 60000 Millisekunden. Für die meisten Performance-Metrik-Anwendungsfälle bleibt TDigest jedoch die praktikablere Wahl, weil es ohne Vorabwissen über den Wertebereich auskommt und trotzdem zuverlässige Ergebnisse liefert.

8. Latenz-Dashboards mit mehreren Perzentilen

Ein aussagekräftiges Latenz-Dashboard zeigt selten nur einen einzelnen Perzentil-Wert, sondern mehrere gleichzeitig, etwa p50, p95 und p99 als übereinanderliegende Linien in einem Zeitreihen-Diagramm. Diese Darstellung macht auf einen Blick sichtbar, ob sich die gesamte Verteilung verschiebt, etwa durch einen langsameren Datenbank-Server, oder ob nur die extremen Perzentile ausreißen, etwa durch gelegentliche Garbage-Collection-Pausen oder einzelne überlastete Knoten.

Für die Aufschlüsselung nach Endpunkt oder Servicename kombiniert man die Percentile Aggregation zusätzlich mit einer Terms-Aggregation, sodass jeder API-Endpunkt seine eigenen p95- und p99-Werte erhält. Diese Kombination deckt häufig auf, dass ein einzelner langsamer Endpunkt die Gesamtmetrik eines Systems dominiert, während die überwiegende Mehrheit der Endpunkte unauffällig performant bleibt, eine Erkenntnis, die ein einzelner globaler Durchschnittswert komplett verschleiern würde.

9. Typische Fehler und Debugging

Der häufigste Fehler im Umgang mit einer Percentile Aggregation ist, TDigest-basierte Perzentile aus mehreren Zeiträumen oder Buckets naiv zu mitteln, um einen Gesamtwert zu approximieren. Das ist statistisch nicht korrekt, weil Perzentile nicht linear kombinierbar sind. Der Mittelwert aus 24 stündlichen p99-Werten ist nicht dasselbe wie der p99 über den gesamten Tag, weil die stündlichen Verteilungen unterschiedliche Formen und Datenmengen haben können.

// WRONG: averaging hourly p99 values to approximate a daily p99
// This produces a statistically meaningless number
avg(p99_hour1, p99_hour2, ..., p99_hour24)

// RIGHT: run a single percentiles aggregation over the full day
{
  "query": {
    "range": { "@timestamp": { "gte": "now-24h" } }
  },
  "aggs": {
    "daily_p99": {
      "percentiles": {
        "field": "response_time_ms",
        "percents": [99]
      }
    }
  }
}

Ein zweiter häufiger Fehler ist, eine Percentile Aggregation auf einer viel zu kleinen Stichprobe laufen zu lassen. Bei nur wenigen hundert Requests pro Bucket schwankt p99 stark und liefert keine belastbaren Aussagen, weil ein einzelner Ausreißer bei dieser geringen Datenmenge das Ergebnis dominiert. Für stabile p99-Werte sollte die zugrunde liegende Datenmenge pro Bucket mindestens im vierstelligen Bereich liegen, sonst ist eine gröbere Zeitgranularität wie Tages- statt Stundenbuckets die bessere Wahl.

10. Zusammenfassung

Die Percentile Aggregation ersetzt den irreführenden Durchschnittswert durch echte Verteilungspunkte und macht damit sichtbar, was ein avg-Wert systematisch verbirgt: die Erfahrung der langsamsten Nutzer. p50 zeigt die typische Erfahrung, p95 und p99 die Erfahrung der langsameren Ausreißer, wobei der TDigest-Algorithmus diese Werte auch bei Milliarden Dokumenten effizient approximiert.

percentile_ranks kehrt die Berechnung um und beantwortet direkt die Frage nach der SLA-Erfüllungsquote. In Kombination mit date_histogram entstehen Latenz-Dashboards, die Trends über die Zeit zeigen, wobei jede Zeitperiode ihre eigene, unabhängige Perzentil-Berechnung braucht, statt Perzentile naiv über Buckets hinweg zu mitteln. Wer diese Bausteine korrekt kombiniert, bekommt belastbare Performance-Metriken statt geglätteter, irreführender Durchschnittswerte.

11. FAQ: Percentile Aggregation für Performance-Metriken