Observabilité : métriques et garde de parité Calcite

Mondrian émet un petit ensemble de métriques OpenTelemetry afin que vous puissiez observer le débit de requêtes, la charge SQL, la localité de cache, et — point important pour le backend Calcite — quand le moteur retombe vers le SQL hérité ou, avec la garde de parité activée, quand les deux backends sont en désaccord.

Brancher un exporter

Les instruments se résolvent contre le SDK OpenTelemetry global. Si votre déploiement configure déjà l’agent Java OpenTelemetry ou autoconfigure (par ex. OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_METRICS_EXPORTER), les métriques de Mondrian y circulent sans configuration supplémentaire. Si aucun SDK n’est enregistré, les instruments sont des no-ops — l’enregistrement est toujours sûr et ne lève jamais d’exception.

Métriques

Métrique	Type	Signification	Attributs clés
mondrian.queries.executed	compteur	Requêtes MDX terminées	mondrian.query.outcome = success | failure
mondrian.query.duration	histogramme (ms)	latence par requête MDX	même outcome
mondrian.sql.statements	compteur	instructions JDBC émises	mondrian.sql.kind (segment-load / member-read / drillthrough / other)
mondrian.sql.duration	histogramme (ms)	latence par instruction JDBC	même kind
mondrian.cache.segment.hits	compteur	demandes de cellules servies depuis le cache de segments	—
mondrian.cache.segment.misses	compteur	demandes de cellules tombées sur un chargement SQL	—
mondrian.calcite.fallback	compteur	la traduction Calcite a levé → repli sur SQL hérité	…fallback.site, …fallback.exception
mondrian.calcite.divergence	compteur	la garde de parité a trouvé que Calcite et l’hérité étaient en désaccord	…divergence.site, …divergence.detail

Un ratio cache.segment.hits / misses élevé signifie une bonne localité de cache. Un calcite.fallback non nul est attendu et bénin — il compte les cas où Calcite a correctement décliné une forme et où le générateur hérité a pris le relais. Le compteur sur lequel alerter est calcite.divergence.

La garde de parité Calcite

Le repli basé sur exception ne capture que « Calcite a levé. » Il ne peut pas attraper la classe dangereuse : le SQL valide-mais-faux — une traduction Calcite qui s’exécute sans erreur mais renvoie un résultat différent du chemin hérité. Cette divergence est invisible au filet de sécurité de repli et ne surface qu’en tant qu’une « aucune donnée » signalée par l’utilisateur ou un total erroné.

La garde de parité comble cette lacune. Lorsqu’elle est activée, chaque chargement de segment Calcite éligible exécute aussi le SQL hérité pour le même chargement et compare les deux jeux de lignes JDBC. Une non-correspondance incrémente mondrian.calcite.divergence (avec une catégorie detail à faible cardinalité — row-count / cell-value, jamais de valeurs brutes) et journalise un WARN.

L’activer

# 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

Les deux sont par défaut off. Lorsque c’est off, le seul coût est une lecture booléenne unique — il n’y a pas d’overhead sur le chemin chaud.

Attention

La garde de parité exécute les deux backends pour chaque chargement inspecté, donc elle double approximativement le travail SQL. C’est un outil de dev / CI / échantillonné, pas un défaut de production. Activez-la dans un environnement de staging ou un job CI qui rejoue des requêtes représentatives, observez mondrian.calcite.divergence, et désactivez-la en production.

Ce qu’elle ne fait jamais (sécurité)

La garde est délibérément ignorée pour deux classes de chargement, afin qu’une divergence enregistrée signifie toujours un vrai bug de correction Calcite — jamais une fausse alarme et jamais un risque de sécurité :

• Chargements sécurisés par prédicat. Un groupe de mesures protégé par un <PredicateGrant> n’est jamais comparé au SQL hérité — le générateur hérité supprime le filtre de sécurité de lignes, donc l’exécuter ferait fuiter des lignes. La sécurité de lignes l’emporte sur les diagnostics, toujours.
• Agrégations correctes uniquement en Calcite. Le grain distinct au niveau de la mesure, médiane / percentile, et pont / fan-out symétrique sont corrects par conception dans Calcite et différents de ce que le générateur hérité calculerait (par ex. une mesure à grain distinct renvoie le 450 dédupliqué là où un SUM hérité naïf renverrait le 950 fanned-out). Les comparer enregistrerait une fausse divergence, donc ils sont ignorés.

En d’autres termes : mondrian.calcite.divergence > 0 est une alerte à fort signal qu’une forme de requête qui devrait être identique entre les backends ne l’est pas. Capturez le contexte de chargement du log WARN et déposez-le comme un bug de correction Calcite.

Alertes recommandées

• Taux de mondrian.calcite.divergence > 0 (quand la garde est activée en staging/CI) → bloquez la release ; une forme de résultat silencieusement erroné existe.
• Taux de mondrian.calcite.fallback en hausse → un dialecte ou une forme de schema que Calcite a cessé de gérer ; vaut la peine d’enquêter pour pushdown perdu, bien que les résultats restent corrects.
• Pic de cache.segment.misses → churn de cache ou cube froid ; envisagez un préchauffage de cache.