Observability: Metriken und der Calcite-Parity-Guard

Mondrian emittiert eine kleine Menge von OpenTelemetry-Metriken, sodass Sie Abfrage-Durchsatz, SQL-Last, Cache-Lokalität und – wichtig für das Calcite-Backend – beobachten können, wann die Engine auf Legacy-SQL zurückfällt oder, mit aktiviertem Parity-Guard, wann die beiden Backends uneinig sind.

Einen Exporter verdrahten

Die Instrumente werden gegen das globale OpenTelemetry-SDK aufgelöst. Wenn Ihr Deployment bereits den OpenTelemetry-Java-Agent oder Autoconfigure konfiguriert (z. B. OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_METRICS_EXPORTER), fließen Mondrians Metriken ohne zusätzlichen Aufwand durch. Wenn kein SDK registriert ist, sind die Instrumente No-ops – das Aufzeichnen ist immer sicher und wirft niemals eine Exception.

Metriken

Metrik	Typ	Bedeutung	Schlüsselattribute
mondrian.queries.executed	counter	Abgeschlossene MDX-Abfragen	mondrian.query.outcome = success | failure
mondrian.query.duration	histogram (ms)	Latenz pro MDX-Abfrage	gleiches outcome
mondrian.sql.statements	counter	Ausgegebene JDBC-Statements	mondrian.sql.kind (segment-load / member-read / drillthrough / other)
mondrian.sql.duration	histogram (ms)	Latenz pro JDBC-Statement	gleicher kind
mondrian.cache.segment.hits	counter	Zellanforderungen aus dem Segment-Cache bedient	—
mondrian.cache.segment.misses	counter	Zellanforderungen, die auf einen SQL-Load durchfielen	—
mondrian.calcite.fallback	counter	Calcite-Übersetzung hat geworfen → Rückfall auf Legacy-SQL	…fallback.site, …fallback.exception
mondrian.calcite.divergence	counter	Parity-Guard fand, dass Calcite und Legacy uneinig waren	…divergence.site, …divergence.detail

Ein hohes cache.segment.hits / misses-Verhältnis bedeutet gute Cache-Lokalität. Ein nicht-null calcite.fallback ist erwartet und harmlos – es zählt Fälle, in denen Calcite eine Form korrekt abgelehnt hat und der Legacy-Generator übernommen hat. Der Counter, auf den Sie alarmieren sollten, ist calcite.divergence.

Der Calcite-Parity-Guard

Der exception-basierte Fallback fängt nur “Calcite hat geworfen”. Er kann die gefährliche Klasse nicht fangen: gültiges-aber-falsches SQL – eine Calcite-Übersetzung, die fehlerfrei läuft, aber ein anderes Ergebnis zurückgibt als der Legacy-Pfad. Diese Divergenz ist für das Fallback-Sicherheitsnetz unsichtbar und taucht nur als vom Benutzer gemeldetes “keine Daten” oder eine falsche Summe auf.

Der Parity-Guard schließt diese Lücke. Wenn aktiviert, führt jeder berechtigte Calcite-Segment-Load auch das Legacy-SQL für denselben Load aus und vergleicht die beiden JDBC-Zeilenmengen. Eine Diskrepanz erhöht mondrian.calcite.divergence (mit einer Low-Cardinality-detail-Kategorie – row-count / cell-value, niemals rohe Werte) und loggt eine WARN.

Aktivierung

# record divergences to telemetry + logs; still returns the Calcite result
-Dmondrian.calcite.parityCheck=true

# additionally hard-fail (throw) on any divergence — for CI / pre-prod gates
-Dmondrian.calcite.parityCheck.strict=true

Beide sind standardmäßig aus. Wenn aus, sind die einzigen Kosten ein einzelnes Boolean-Lesen – es gibt keinen Hot-Path-Overhead.

Achtung

Der Parity-Guard führt beide Backends für jeden inspizierten Load aus und verdoppelt damit etwa die SQL-Arbeit. Es ist Dev / CI / gesampelte Werkzeugausstattung, kein Produktions-Standard. Schalten Sie ihn in einer Staging-Umgebung oder einem CI-Job ein, der repräsentative Abfragen wiederholt, beobachten Sie mondrian.calcite.divergence und schalten Sie ihn in der Produktion wieder aus.

Was er niemals tut (Sicherheit)

Der Guard wird absichtlich für zwei Klassen von Loads übersprungen, sodass eine aufgezeichnete Divergenz immer einen echten Calcite-Korrektheits-Bug bedeutet – niemals einen Fehlalarm und niemals ein Sicherheitsrisiko:

• Predicate-gesicherte Loads. Eine durch einen <PredicateGrant> geschützte Measure-Group wird niemals mit Legacy-SQL verglichen – der Legacy-Generator lässt den Zeilensicherheitsfilter weg, sodass ein Ausführen Zeilen leaken würde. Zeilensicherheit gewinnt immer über Diagnostik.
• Nur-Calcite-korrekte Aggregationen. Distinct-Granularität auf Measure-Ebene, median / percentile und Bridge / symmetrischer Fan-Out sind in Calcite by design korrekt und unterscheiden sich von dem, was der Legacy-Generator berechnen würde (z. B. gibt eine Distinct-Granularitäts-Measure die deduplizierten 450 zurück, wo ein naives Legacy-SUM die expandierten 950 zurückgeben würde). Sie zu vergleichen würde eine Fehl-Divergenz aufzeichnen, daher werden sie übersprungen.

Anders gesagt: mondrian.calcite.divergence > 0 ist ein hochsignifikanter Alarm, dass eine Abfrageform, die backend-übergreifend identisch sein sollte, es nicht ist. Erfassen Sie den Load-Kontext des WARN-Logs und melden Sie es als Calcite-Korrektheits-Bug.

Empfohlene Alarme

• mondrian.calcite.divergence-Rate > 0 (wenn der Guard in Staging/CI aktiviert ist) → das Release blockieren; eine still-falsche Ergebnisform existiert.
• mondrian.calcite.fallback-Rate steigend → ein Dialekt oder eine Schema-Form, die Calcite nicht mehr verarbeitet; sollte untersucht werden für verlorenes Pushdown, obwohl Ergebnisse korrekt bleiben.
• cache.segment.misses-Spitzen → Cache-Churn oder ein kalter Cube; erwägen Sie Cache-Warming.