Prometheus Native Histograms: Migration mit Rollback

Bei einem direkten Wechsel fehlen der nativen Basismetrik alle Werte vor dem Umschaltzeitpunkt. Eine 30-Tage-Abfrage enthält dann beispielsweise nur den seit dem Wechsel erfassten Teil. Falls dieselbe Zeitreihe innerhalb eines Range-Vektors Float- und Histogramm-Samples mischt, verwirft PromQL die betroffene Reihe in Funktionen wie rate() und gibt eine Warnung aus. Ein harter Cutover ist deshalb die falsche Migrationsstrategie.

Der Parallelbetrieb hält klassische _bucket-Reihen verfügbar, während neue Regeln die native Basismetrik auswerten. Native Histograms gelten ab Prometheus 3.8 als stabil. Ab Version 3.9 hat das frühere Feature-Flag --enable-feature=native-histograms keine Wirkung mehr. Die Scrape-Optionen scrape_native_histograms und always_scrape_classic_histograms steuern stattdessen, welche Darstellungen Prometheus übernimmt.

Schritt 1: Abhängigkeiten von klassischen Histogrammen erfassen

Namenssuffixe wie _bucket, _sum und _count liefern eine erste Kandidatenliste. Die Abfrage erfasst allerdings auch Summaries und Metriken, deren Namen nur zufällig auf diese Zeichenfolgen enden.

{__name__=~".*_(bucket|sum|count)$"}

Die Abhängigkeitskarte umfasst alle Stellen, die klassische Buckets oder das Label le auswerten:

• Recording Rules und Alerting Rules mit histogram_quantile()
• Grafana-Panels, Variablen, Transformationen und Datenlinks
• Remote-Write-Empfänger und Langzeitspeicher
• Federation-Ziele und externe Prometheus-Instanzen
• APIs, Exporte und nachgelagerte Auswertungen

Das längste Zeitfenster aus Dashboards, Alerts, SLO-Auswertungen oder Berichten bestimmt später die Mindestdauer des Parallelbetriebs. Diese Karte zeigt zugleich, welche Dateien und Datenpfade vor dem Pilotbetrieb gesichert und getestet werden müssen.

Schritt 2: Version, Konfiguration und Ausgangsbasis prüfen

Der Pilot läuft auf einer veröffentlichten und für die eigene Umgebung unterstützten Prometheus-Version. Das Team prüft für jede übersprungene Version entfernte Optionen, geänderte Standardwerte und bekannte Inkompatibilitäten. promtool findet Syntaxfehler in Konfiguration und Regeln, bevor die neue Instanz startet.

promtool check config /etc/prometheus/prometheus.yml
promtool check rules /etc/prometheus/rules/*.yml

Das Team exportiert die Prometheus-Konfiguration, die Regeldateien und die Grafana-Dashboards. Ein TSDB-Snapshot kommt hinzu, wenn die Wiederherstellungsplanung lokale Zeitreihendaten einschließt. Externe Langzeitspeicher benötigen eine eigene Sicherungs- und Rückleseprüfung.

Messwerte für die Ausgangsbasis

Die Ausgangsbasis trennt Veränderungen durch Native Histograms von Fehlern, die bereits vorher bestanden. Erst mit diesem Vergleichswert beginnt der Pilot.

Schritt 3: Native Histograms für einen Pilot aktivieren

Die Scrape-Optionen gelten pro scrape_config. Die Service-Discovery oder eine getrennte Job-Konfiguration muss Pilot-Targets deshalb eindeutig auswählen, damit Prometheus dasselbe Target nicht versehentlich doppelt unter identischen Labels erfasst.

scrape_configs:
  - job_name: app-native-pilot
    scrape_native_histograms: true
    always_scrape_classic_histograms: true
    static_configs:
      - targets:
          - app-pilot.example:9464

always_scrape_classic_histograms behält die klassische Darstellung nur dann bei, wenn der instrumentierte Dienst beide Darstellungen bereitstellt. Der Pilot prüft daher zuerst die tatsächliche Exposition des Exporters oder der Client-Bibliothek. Eine Kontrollgruppe mit ähnlichem Lastprofil bleibt unverändert und liefert die Referenz für den PromQL-Vergleich.

Schritt 4: PromQL für beide Histogrammformate vergleichen

p95 aus klassischen Buckets berechnen

Die klassische Abfrage aggregiert über das Bucket-Label le. Ohne dieses Label kann histogram_quantile() die kumulativen Buckets nicht unterscheiden.

histogram_quantile(
  0.95,
  sum by (job, le) (
    rate(http_request_duration_seconds_bucket[5m])
  )
)

p95 aus einem Native Histogram berechnen

Das Native-Histogram-Sample enthält seine Bucket-Struktur. Die Abfrage verwendet deshalb den Namen der Basismetrik und aggregiert nicht über le.

histogram_quantile(
  0.95,
  sum by (job) (
    rate(http_request_duration_seconds[5m])
  )
)

Ein gemeinsames sum() darf Float-Samples klassischer Buckets und Native-Histogram-Samples nicht in derselben Ausgabegruppe mischen. PromQL entfernt eine solche Gruppe und kennzeichnet sie mit einer Warnung. Getrennte Recording Rules, etwa mit den Suffixen p95_classic und p95_native, halten beide Ergebnisse während der Quantilprüfung vergleichbar.

Schritt 5: Quantile und Datenkontinuität validieren

Klassische und native Histogramme schätzen Quantile aus unterschiedlichen Bucket-Strukturen. Identische Ergebnisse sind daher kein geeignetes Akzeptanzkriterium. Das Team legt absolute oder relative Toleranzen anhand der Einheit, des SLO-Grenzwerts und der beobachteten Ereigniszahl fest.

Die Prüfung deckt mehrere Bedingungen ab:

• p50, p95 und p99
• Normale Last und bekannte Lastspitzen
• Zeitfenster mit wenigen Beobachtungen
• Instant Queries und Range Queries
• Abfragezeiträume rund um den Umschaltzeitpunkt

Eine eigene Zeitreihe kann die absolute Abweichung sichtbar machen:

abs(
  job:http_request_duration_seconds:p95_native
-
  job:http_request_duration_seconds:p95_classic
)

Leere Panels, fehlende Datenpunkte, PromQL-Warnungen oder veränderte Label-Gruppen zählen als Fehlerindikatoren. Erst wenn die nativen Regelreihen die festgelegten Toleranzen einhalten, beginnt die Migration von Grafana und Alerting.

Schritt 6: Grafana-Dashboards und Alerts migrieren

Ein dupliziertes Panel zeigt klassische und native Ergebnisse im selben Zeitraum. Der Vergleich umfasst mehr als den angezeigten Zahlenwert:

• Legenden und Einheiten
• Schwellwerte und Farbstufen
• Dashboard-Variablen
• Transformationen und Panel-Berechnungen
• Datenlinks
• Minimale und maximale Achsenwerte

Bei Alerts zählen auch die Wechsel nach NoData, Pending und Resolved. Die Umstellung beginnt bei den Recording Rules, danach folgen Alert-Ausdrücke und Dashboards. Frühere Regeldateien und Dashboard-Versionen bleiben für den Rollback erhalten.

Die Schulung zu Monitoring mit Prometheus und Grafana vertieft PromQL, Dashboard-Konfiguration, Alerting und Fehlersuche. Nach den lokalen Abfragen folgen alle externen Schreib- und Lesepfade.

Schritt 7: Remote Write und OpenTelemetry testen

Eine erfolgreiche HTTP-Antwort belegt nur, dass der Empfänger die Anfrage angenommen hat. Der Test muss zeigen, dass der vollständige Datenpfad Native Histograms ohne unbemerkte Umwandlung oder Verwerfung verarbeitet.

• Schreibfehler und Wiederholungen
• Wachsende Remote-Write-Queues
• Verworfene Samples
• Rückleseabfragen aus dem Langzeitspeicher
• Quantile, Summen und Beobachtungszahlen nach der Rückleseabfrage

OpenTelemetry Exponential Histograms und Prometheus Native Histograms verwenden exponentielle Bucket-Schemata, sind aber nicht in jedem Datenpfad automatisch austauschbar. Collector-Konfiguration, Exporter und Speicher bestimmen, ob eine Übersetzung stattfindet und welche Eigenschaften erhalten bleiben. Ein End-to-End-Test vergleicht deshalb Beobachtungszahl, Summe und ausgewählte Quantile vom instrumentierten Dienst bis zum Grafana-Panel.

Die Schulung zu Prometheus, Grafana und OpenTelemetry für Kubernetes behandelt diesen Datenpfad für Kubernetes-Metriken. Die Ergebnisse der Kompatibilitätsprüfung liefern zugleich die Messpunkte für den anschließenden Lasttest.

Schritt 8: Bucket-Wachstum und Ressourcenverbrauch begrenzen

Ein Histogramm mit weit auseinanderliegenden Beobachtungswerten kann viele belegte Buckets erzeugen. Das erhöht den Speicherbedarf pro Sample und belastet Abfragen sowie Remote Write. Extern steuerbare Beobachtungswerte verdienen besondere Aufmerksamkeit, weil sie eine ungewöhnlich breite Verteilung auslösen können.

Die Scrape-Konfiguration stellt dafür native_histogram_bucket_limit und native_histogram_min_bucket_factor bereit. Die erste Option begrenzt die akzeptierte Bucket-Anzahl. Die zweite kann die Auflösung reduzieren. Das Verhalten beim Überschreiten der Grenze hängt von der gewählten Konfiguration ab und wird mit absichtlich breiten Testwerten geprüft.

Der Lasttest erfasst:

• Arbeitsspeicher und CPU-Zeit
• TSDB-Wachstum
• Aufnahmerate
• Sample-Größe
• PromQL-Allokationen und Abfragelatenz
• Remote-Write-Volumen

Warn- und Abbruchschwellen leiten sich aus der gemessenen Ausgangsbasis und den Kapazitätsgrenzen der Umgebung ab. Nach bestandener Lastprüfung bestimmt das längste historische Abfragefenster die Dauer der parallelen Erfassung.

Schritt 9: Beide Formate über das historische Zeitfenster erfassen

Ein Dashboard mit einem 30-Tage-Zeitraum benötigt mindestens 30 Tage native Daten, bevor seine Abfrage vollständig auf die native Metrik wechselt. Längere Alert-Rückblicke, SLO-Fenster oder Kapazitätsberichte verlängern den Parallelbetrieb entsprechend. Die Aufbewahrungszeit muss dieses Fenster ebenfalls abdecken.

Klassische Metriken bleiben während des vereinbarten Rollback-Fensters aktiv. Sonst fehlen nach einer Rückkehr zur klassischen Abfrage die Samples, die seit der Abschaltung entstanden wären. Erst ein vollständig gefülltes natives Zeitfenster und ein weiterhin nutzbarer Rückweg erlauben die stufenweise Umschaltung.

Schritt 10: Rollback-Kriterien festlegen und Umschaltung abschließen

Das Runbook verknüpft jeden Abbruchgrund mit einem messbaren Signal. Typische Auslöser sind:

• Fehlende Samples oder Datenlücken
• Quantilabweichungen außerhalb der vereinbarten Toleranz
• Fehler in Remote Write oder bei Rückleseabfragen
• Ressourcenverbrauch oberhalb der Abbruchschwelle
• Unbeabsichtigte Wechsel von Alert-Zuständen

Für Entscheidung, technische Umsetzung und anschließende Validierung sind getrennte Verantwortlichkeiten dokumentiert. Der Rückweg aktiviert die klassischen Histogramme erneut und stellt die vorherigen Regeln sowie Dashboards wieder her. Das Team testet diesen Ablauf im Pilotbetrieb, bevor weitere Target-Gruppen wechseln.

Nach der Umschaltung hält das Protokoll Ressourcenverbrauch, Abfragelatenzen, Quantilabweichungen und erkannte Datenlücken fest. Diese Werte vervollständigen die Checkliste für weitere Target-Gruppen.

Checkliste für das Produktions-Runbook

• Metriken und ihre Abhängigkeiten inventarisieren
• Eine unterstützte Prometheus-Version auswählen
• Konfiguration und Regeln mit promtool prüfen
• Ausgangsbasis und Abbruchschwellen dokumentieren
• Beide Histogrammformate für Pilot-Targets erfassen
• PromQL-Ergebnisse und Quantile automatisiert vergleichen
• Grafana, Remote Write und OpenTelemetry durchgängig testen
• Das längste historische Zeitfenster parallel abdecken
• Rollback im Pilotbetrieb ausführen
• Target-Gruppen stufenweise umstellen

Weitere technische Schulungen bündelt die Kategorie Monitoring und Logging. Starte den Produktionslauf mit einem repräsentativen Target, einer unveränderten Kontrollgruppe und schriftlich festgelegten Abbruchschwellen.