From 9b54ddc483b0cb2854026a03dd2f83dfa6c483c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez?= Date: Thu, 16 Jul 2026 12:02:36 +0200 Subject: [PATCH] feat(observability): gated histogram buckets for firefly.* + honest exemplars doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add management.metrics.distribution.percentiles-histogram.firefly, gated by FIREFLY_OBSERVABILITY_METRICS_HISTOGRAMS_ENABLED and DEFAULT OFF. When enabled it applies a Micrometer MeterFilter to every firefly.* meter so p99 becomes aggregable across pods (histogram_quantile()) and metric→trace exemplars can anchor to _bucket samples. Ships inert so there is no cardinality impact until the platform opts in; the client-side publishPercentiles are unaffected. Also correct the ExemplarsAutoConfiguration Javadoc: exemplars are NOT functional in the current scrape→collector→store pipeline (no buckets by default, 0.0.4 exposition, exemplars dropped in transit). Stop promising metric→trace click-through and document the three unmet preconditions. --- .../actuator/ExemplarsAutoConfiguration.java | 27 ++++++++++--------- .../application-firefly-observability.yml | 10 +++++++ 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/src/main/java/org/fireflyframework/observability/actuator/ExemplarsAutoConfiguration.java b/src/main/java/org/fireflyframework/observability/actuator/ExemplarsAutoConfiguration.java index 64aa077..931656a 100644 --- a/src/main/java/org/fireflyframework/observability/actuator/ExemplarsAutoConfiguration.java +++ b/src/main/java/org/fireflyframework/observability/actuator/ExemplarsAutoConfiguration.java @@ -7,19 +7,22 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; /** - * Auto-configuration for Prometheus exemplar linking. + * Placeholder for Prometheus exemplar linking. Exemplars are NOT functional in the + * current pipeline — do not rely on metric→trace click-through yet. *

- * When both tracing and Prometheus are active, exemplars are auto-configured by - * Spring Boot. This configuration ensures the framework's tracing setup is - * compatible with exemplar generation, enabling users to click a Prometheus - * metric in Grafana and jump directly to the trace that caused it. - *

- * Requirements: - *

+ * This class does not wire anything; it is a documentation/activation marker. For + * exemplars to actually link a metric sample to a trace, three conditions must ALL hold, + * and none is met today: + *
    + *
  1. The {@code firefly.*} timers must publish histogram {@code _bucket} samples — + * exemplars anchor to buckets, and buckets are OFF by default (enable via + * {@code management.metrics.distribution.percentiles-histogram.firefly=true}).
    2. + *
  2. The exposition must be OpenMetrics 1.0.0 (exemplars are an OpenMetrics feature).
    3. + *
  3. The scrape→collector→store pipeline must preserve OpenMetrics exemplars end to + * end; the current scrape-to-GreptimeDB path drops them.
    4. + *
+ * Until the pipeline supports it, correlate metrics to traces via shared resource + * attributes ({@code application}, {@code k8s_pod_name}) plus timestamp, not exemplars. */ @AutoConfiguration @ConditionalOnClass(name = "io.micrometer.prometheusmetrics.PrometheusMeterRegistry") diff --git a/src/main/resources/application-firefly-observability.yml b/src/main/resources/application-firefly-observability.yml index c7f3032..54fc80e 100644 --- a/src/main/resources/application-firefly-observability.yml +++ b/src/main/resources/application-firefly-observability.yml @@ -66,6 +66,16 @@ management: metrics: tags: application: ${spring.application.name:unknown} + ## Histogram buckets (le) for firefly.* timers/summaries — DEFAULT OFF. + ## When enabled, p99 becomes aggregable across pods (histogram_quantile()) and it + ## is the prerequisite for metric→trace exemplars, at the cost of extra series + ## cardinality per timer. Ships inert; platform flips it on when the cardinality + ## budget is approved: FIREFLY_OBSERVABILITY_METRICS_HISTOGRAMS_ENABLED=true. + ## Applies a Micrometer MeterFilter to every meter whose name starts with "firefly"; + ## the existing client-side publishPercentiles are unaffected. + distribution: + percentiles-histogram: + firefly: ${FIREFLY_OBSERVABILITY_METRICS_HISTOGRAMS_ENABLED:false} tracing: enabled: ${firefly.observability.tracing.enabled:true} sampling: