feat(observability): gated histogram buckets for firefly.* + honest exemplars doc

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. <b>Exemplars are NOT functional in the
+ * current pipeline</b> — do not rely on metric→trace click-through yet.
  * <p>
- * 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.
- * <p>
- * Requirements:
- * <ul>
- *     <li>{@code micrometer-registry-prometheus} on classpath</li>
- *     <li>{@code micrometer-tracing-bridge-otel} or {@code micrometer-tracing-bridge-brave} on classpath</li>
- *     <li>Prometheus must be configured with exemplar support (OpenMetrics format)</li>
- * </ul>
+ * 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:
+ * <ol>
+ *     <li>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}).</li>
+ *     <li>The exposition must be OpenMetrics 1.0.0 (exemplars are an OpenMetrics feature).</li>
+ *     <li>The scrape→collector→store pipeline must preserve OpenMetrics exemplars end to
+ *         end; the current scrape-to-GreptimeDB path drops them.</li>
+ * </ol>
+ * 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")

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: