Luigi De Masi created CAMEL-25648:
-------------------------------------
Summary: camel-semantic - Micrometer metrics and Prometheus
monitoring history
Key: CAMEL-25648
URL: https://issues.apache.org/jira/browse/CAMEL-25648
Project: Camel
Issue Type: Improvement
Components: camel-jbang, camel-ai, camel-micrometer
Reporter: Luigi De Masi
Assignee: Luigi De Masi
h2. Motivation
Follow up CAMEL-25618 and [PR
#27791|https://github.com/apache/camel/pull/27791] with an optional integration
for production semantic monitoring through Micrometer and Prometheus.
The semantic audit/monitoring foundation supplies typed events, shared
measurements and bounded local history. It does not yet export semantic
measurements to Micrometer or query Prometheus history. Operators should be
able to monitor evaluation rates, execution failures, latency and
returned-result distributions across application instances and restarts, and
inspect retained measurements without keeping the TUI open.
h2. Scope
h3. Shared semantic metrics integration
* Add an optional runtime-independent integration using Micrometer's
{{MeterRegistry}}. Reuse the application/runtime registry and its lifecycle;
keep Micrometer and Prometheus optional dependencies for semantic users.
* Use the typed semantic event/measurement foundation from CAMEL-25618. Give
each measurement one ingestion path, independent of audit retention, input
capture, JMX and UI polling. Avoid duplicate counts from request lifecycle
events, batch envelopes or concurrent monitoring consumers.
* Record completed assessment members, execution outcomes, result availability
and evaluation duration. Keep provider attempts/retries separate from semantic
completions. Record duration observations in timers/histograms so percentiles
can be queried correctly; do not reconstruct percentiles from snapshot means.
* Preserve Boolean, choice, score and classification semantics in result
counts/distributions. Failures or missing results are not false answers;
probability entries are not additional completed answers; classification may
select multiple labels. Export expert-supplied measurements only when their
units and aggregation semantics permit a documented mapping.
* Support aggregation by expert or definition using consistent, bounded
dimensions. Direct expert calls remain distinguishable from definition
evaluations. Bound series/cardinality and expose collection exclusions or loss.
Do not use prompts, input, free-form interpretation, exception messages,
exchange IDs, breadcrumb IDs or invocation IDs as metric labels.
* Keep event callbacks short. Scraping, historical queries and backend I/O must
not block evaluation callbacks. Monitoring failures must not change the
assessment result.
h3. Runtime integration
Use the same metric names, units, labels and counting semantics in all three
runtimes, with each runtime supplying its normal registry and HTTP exposure:
||Runtime||Existing integration to reuse||
|Camel Main|{{camel-micrometer-prometheus}} and the management metrics
endpoint.|
|Camel Spring Boot|{{camel-micrometer-starter}}, Spring Boot Actuator and
{{micrometer-registry-prometheus}}.|
|Camel Quarkus|{{camel-quarkus-micrometer}} and
{{quarkus-micrometer-registry-prometheus}}.|
Provide configuration/examples and integration coverage for all three,
coordinating starter/extension changes in their respective repositories.
Validate the new integration on the JVM and in a supported Quarkus native
configuration; existing Micrometer native support alone is not proof of
semantic integration support.
h3. Persistence and historical monitoring
Prometheus scrapes the exposed metrics and owns time-series storage and
retention. Micrometer records measurements in the application; it is not the
durable backend.
Add an optional Prometheus query integration for the shared monitoring read
path, allowing the monitoring UI to select time ranges and aggregate by expert
or definition. Keep queries bounded by time, resolution, series count, response
size and timeout. Present actual data coverage, units, grouping and
availability; distinguish absent/stale data or query failures from zero values.
Support counter resets and multiple instances without implying that runtime
counters or detector state were restored.
A Prometheus integration is not a direct implementation of
{{SemanticMonitoringStore.append(snapshot)}} / {{readRecent(limit)}}: time
series do not preserve complete snapshot documents, interpretation or example
references. Define the historical query capability separately while preserving
bounded local monitoring for deployments without Prometheus. UI pause and
visualization controls must not alter collection or retention.
h2. Acceptance criteria
# A runnable example in each runtime exposes equivalent semantic metrics to a
real Prometheus scrape, with documented setup and queries for evaluation rate,
failure rate, duration and result distributions.
# Tests cover audit-disabled operation, direct and definition evaluations,
batches, failures, restart/reset behavior, duplicate-count prevention and
bounded cardinality.
# Histogram-based latency queries use actual duration observations. Result
metrics retain their assessment meaning and never imply route actions, accuracy
loss or security incidents.
# Historical monitoring queries operate over retained Prometheus data with
expert/definition grouping and explicit coverage/unavailability, including
empty, stale and failed responses.
# Documentation explains registry ownership, scrape cadence, labels, units,
retention, multi-instance aggregation and the distinction between metric
history, local snapshots and audit records.
# No new inference, synthetic demonstration measurements or raw-input retention
is required for monitoring.
h2. References
* CAMEL-25618
* [Camel Main Micrometer
Prometheus|https://camel.apache.org/components/next/others/micrometer-prometheus.html]
* [Camel Spring Boot
Micrometer|https://camel.apache.org/camel-spring-boot/next/starters/micrometer.html]
* [Camel Quarkus
Micrometer|https://camel.apache.org/camel-quarkus/next/reference/extensions/micrometer.html]
----
_AI-generated by Codex on behalf of
[luigidemasi|https://github.com/luigidemasi]._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
