[
https://issues.apache.org/jira/browse/CAMEL-25648?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Luigi De Masi updated CAMEL-25648:
----------------------------------
Description:
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 and current
measurements through a bounded runtime cache. It does not yet export semantic
measurements to Micrometer. Durable time-series history, querying, analysis and
correlation belong to the external monitoring system. Operators should be able
to monitor evaluation rates, execution failures, latency and returned-result
distributions across application instances and restarts, using the monitoring
backend independently of the Camel TUI.
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,
correlation IDs, exchange IDs, breadcrumb IDs or invocation IDs as metric
labels. Keep per-execution identifiers in audit/log/trace records. Standard
trace/span exemplars may provide sampled links where runtime tracing and the
registry support them, without unique metric labels or Camel-owned example
audit-event ID lists.
* 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. Responsibility boundary
Micrometer records measurements in the application registry. Prometheus scrapes
them and owns time-series storage and retention. Grafana or another monitoring
application owns historical queries, time selection, comparisons, anomaly
detection, alerting, dashboards and cross-signal navigation.
This issue adds instrumentation and export only: no SemanticMonitoringStore
implementation, snapshot-document persistence, Prometheus query client in
Camel, historical TUI integration, baseline/comparison model or example
audit-event IDs. Camel's local Monitoring view remains a current-value
inspector and works without Prometheus.
Provide example PromQL queries for operators to use in their monitoring
backend, including rates, result distributions, latency histograms, counter
resets and multiple instances. Do not turn those examples into a Camel query
service. Audit investigation can filter a matching [since, until) interval,
definition/operation and typed result. Audit capture and retention may cover
only a subset of the monitored population; per-evaluation correlation labels
are unnecessary.
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.
# Example backend queries cover expert/definition grouping, rates, counter
resets and multi-instance aggregation. Historical queries and presentation
remain in the monitoring backend; Camel adds no history-query service or
dashboard engine.
# Documentation explains registry ownership, scrape cadence, labels, units,
retention, multi-instance aggregation and the distinction between backend
metric history, transient current-value reads and independently retained audit
records. Document exemplar availability/limits without promising one link per
evaluation.
# 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]._
was:
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]._
Summary: camel-semantic - Micrometer instrumentation and Prometheus
export (was: camel-semantic - Micrometer metrics and Prometheus monitoring
history)
> camel-semantic - Micrometer instrumentation and Prometheus export
> -----------------------------------------------------------------
>
> Key: CAMEL-25648
> URL: https://issues.apache.org/jira/browse/CAMEL-25648
> Project: Camel
> Issue Type: Improvement
> Components: camel-ai, camel-jbang, camel-micrometer
> Reporter: Luigi De Masi
> Assignee: Luigi De Masi
> Priority: Major
>
> 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 and current
> measurements through a bounded runtime cache. It does not yet export semantic
> measurements to Micrometer. Durable time-series history, querying, analysis
> and correlation belong to the external monitoring system. Operators should be
> able to monitor evaluation rates, execution failures, latency and
> returned-result distributions across application instances and restarts,
> using the monitoring backend independently of the Camel TUI.
> 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, correlation IDs, exchange IDs, breadcrumb IDs or invocation IDs as
> metric labels. Keep per-execution identifiers in audit/log/trace records.
> Standard trace/span exemplars may provide sampled links where runtime tracing
> and the registry support them, without unique metric labels or Camel-owned
> example audit-event ID lists.
> * 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. Responsibility boundary
> Micrometer records measurements in the application registry. Prometheus
> scrapes them and owns time-series storage and retention. Grafana or another
> monitoring application owns historical queries, time selection, comparisons,
> anomaly detection, alerting, dashboards and cross-signal navigation.
> This issue adds instrumentation and export only: no SemanticMonitoringStore
> implementation, snapshot-document persistence, Prometheus query client in
> Camel, historical TUI integration, baseline/comparison model or example
> audit-event IDs. Camel's local Monitoring view remains a current-value
> inspector and works without Prometheus.
> Provide example PromQL queries for operators to use in their monitoring
> backend, including rates, result distributions, latency histograms, counter
> resets and multiple instances. Do not turn those examples into a Camel query
> service. Audit investigation can filter a matching [since, until) interval,
> definition/operation and typed result. Audit capture and retention may cover
> only a subset of the monitored population; per-evaluation correlation labels
> are unnecessary.
> 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.
> # Example backend queries cover expert/definition grouping, rates, counter
> resets and multi-instance aggregation. Historical queries and presentation
> remain in the monitoring backend; Camel adds no history-query service or
> dashboard engine.
> # Documentation explains registry ownership, scrape cadence, labels, units,
> retention, multi-instance aggregation and the distinction between backend
> metric history, transient current-value reads and independently retained
> audit records. Document exemplar availability/limits without promising one
> link per evaluation.
> # 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)
