improve and align activemq classic JMX metrics with semconv

[SylvainJuge]

Fixes #14278

Only covers ActiveMQ Classic, ActiveMQ Artemis will be covered with #15006.

Some of the ActiveMQ metrics are provided as percentages with integer values in [0,100] range, this PR adds a % to 1 unit conversion to translate this to [0.0,1.0] range.

For the resource-related metrics, this follows the same strategy we have on GPU hardware metrics (semconv)

• hw.gpu.memory.usage to measure usage in bytes
• hw.gpu.memory.limit to measure limit in bytes
• hw.gpu.memory.utilization as usage ratio between 0.0 and 1.0

Summary of changes

Metric attributes

• messaging.system metric attribute added to all metrics with activemq constant value
• broker metric attribute is renamed to activemq.broker.name
• destination metric attribute is renamed to messaging.destination.name

New metrics

Destination (queue/topic) resource usage and configured limits

• activemq.destination.memory.usage, value in bytes (see related item to discuss below)
• activemq.destination.memory.limit, value in bytes
• activemq.destination.temp.utilization, value in [0.0,1.0] converted from [0,100]
• activemq.destination.temp.limit, value in bytes

Broker resource usage and configured limits

• activemq.memory.utilization, value in [0.0,1.0] converted from [0,100]
• activemq.memory.limit, value in bytes
• activemq.store.utilization, value in [0.0,1.0] converted from [0,100]
• activemq.store.limit, value in bytes
• activemq.temp.utilization, value in [0.0,1.0] converted from [0,100]
• activemq.temp.limit, value in bytes

Removed metrics

• activemq.memory.MemoryPercentUsage metric removed, replaced by activemq.destination.memory.usage and activemq.destination.memory.limit

Renamed metrics

• activemq.ProducerCount metric renamed to activemq.producer.count
• activemq.ConsumerCount metric renamed to activemq.consumer.count
• activemq.message.QueueSize metric renamed to activemq.message.queue.size
• activemq.message.ExpiredCount metric renamed to activemq.message.expired
• activemq.message.EnqueueCount metric renamed to activemq.message.enqueued (with an extra d for consistency with expired.
• activemq.message.DequeueCount metric renamed to activemq.message.dequeued (with an extra d for consistency with expired.
• activemq.message.AverageEnqueueTime metric renamed to activemq.message.enqueue.average_duration (see related item to discuss below)

Things to potentially discuss/clarify

• should we set messaging.system metric attribute to constant value activemq when we monitor activemq itself or is it only meant on the application side ? Because metric names are already part of activemq.* namespace it might be a bit redundant, but could help with correlation with traces from application. Also, the messaging.system is about to be renamed to messaging.system.name, removing this attribute would avoid one known breaking change.
  • answer: remove it. While this allows to directly correlate with tracing data, this is mostly redundant with the metric name prefix, so we remove it for now (it could be added later for convenience if needed).
• When we only have an average value exposed through JMX like activemq.message.enqueue.average_duration, does using the same convention as k8s.hpa.metric.target.cpu.average_utilization is a good fit ?
• per-destination resource usage and limit metrics have been moved to a destination "sub-namespace" activemq.{memory,temp}.destination.* , the broker-level equivalents were not previously captured, they are expected to be more global and thus in the activemq.{memory,temp,store}.* namespace.
• we can capture the destination memory usage in bytes with activemq.destination.memory.usage, but we can't do the same with non-persistent storage which is always captured as a ratio between 0.0 and 1.0, should we favor consistency between similar metrics or give priority to accuracy ? Ratio is provided through an int percentage, thus max 1% accuracy. We could also provide both activemq.destination.memory.usage and activemq.destination.memory.utilization here. On the monitoring side, having an exact measurement is probably not required.

[otelbot-java-instrumentation]

🔧 The result from spotlessApply was committed to the PR branch.

[github-actions]

⚠️ Breaking Change Documentation Required

This PR has been labeled as a breaking change. Please ensure you provide the following information:

Migration Notes Required

Please add detailed migration notes to help users understand:

• What is changing and why
• How to update their code/configuration
• Any alternative approaches if applicable
• Code examples showing before/after usage

Checklist

• Migration notes added to the PR description
• Breaking change is documented in the changelog entry for the next release
• Consider if this change requires a major version bump

Your migration notes will be included in the release notes to help users upgrade smoothly. The more detailed and helpful they are, the better the user experience will be.

---

This comment was automatically generated because the breaking change label was applied to this PR.

[robsunday]

Just for clarification, description above:

activemq.message.DequeueCount metric renamed to activemq.message.enqueued (with an extra d for consistency with expired.

shoud be:
activemq.message.DequeueCount metric renamed to activemq.message.dequeued (with an extra d for consistency with expired.)

right?
I'm asking because this nice description of changes may be directly copied to release notes.

[robsunday]

Consider messaging.activemq.broker.name

[thompson-tomo]

Or even messaging.brooker.name so it can be reused.

[robsunday]

Is messaging.broker.name a part of semconv?

[thompson-tomo]

Not currently but it could be added.

[SylvainJuge]

In order to generalize activemq.broker.name by adding messaging.broker.name to semconv we need to have more than one implementation to serve as an example (this PR provides one).

From experience, it usually takes a while as name-related discussions always take time to settle, I don't think we should make this PR depend on it. We can always iterate on it later and change that once a stable semconv attribute is available.

[SylvainJuge]

Just for clarification, description above:

activemq.message.DequeueCount metric renamed to activemq.message.enqueued (with an extra d for consistency with expired.

shoud be: activemq.message.DequeueCount metric renamed to activemq.message.dequeued (with an extra d for consistency with expired.)

right? I'm asking because this nice description of changes may be directly copied to release notes.

Good catch, I've updated the PR description, should be good now.

[thompson-tomo]

Looking at https://opentelemetry.io/docs/specs/semconv/general/naming/#client-and-server-metrics should alot of these metrics actually become activemq.server.* or perhaps activemq.brooker.* as Brooker would indicate that it is the server, just like process does indicate that it is client.

Also shouldn't activemq.message.ExpiredCount become activemq.expired.message/activemq.brooker.expired.message based on the naming guidance

[SylvainJuge]

constant messaging.system as been removed following related slack discussion.

[SylvainJuge]

Looking at https://opentelemetry.io/docs/specs/semconv/general/naming/#client-and-server-metrics should alot of these metrics actually become activemq.server.* or perhaps activemq.brooker.* as Brooker would indicate that it is the server, just like process does indicate that it is client.

In the client and server metrics, I think that ActiveMQ fits the last example where activemq prefix makes it implicitly messaging related, I don't think we need to further qualify it as a "server" or "broker".

Example about the "kestrel" http server:

kestrel.connection.duration - here, kestrel is the name of the web server, so no additional indication is necessary.

Also shouldn't activemq.message.ExpiredCount become activemq.expired.message/activemq.brooker.expired.message based on the naming guidance

I haven't seen anything explicitly written in semconv, but I think there is a different strategy to name attributes and metrics, maybe it's because I'm not a native english speaker:

• metrics are structured by namespace and functional scope: so activemq.message.* will contain all the message-related metrics of activemq
• attributes are named after things they observe, thus here the order of things tend to look like more a sentence.

[thompson-tomo]

@SylvainJuge for me the key part of that link is:

Metrics that measure some aspect of a physical or logical network call SHOULD include an indication of which side the metric is being recorded from.

Such metrics SHOULD follow the {area}.{client|server}.{metric_name} pattern

In the case here, ActiveMQ would be the area and in fact it would actually make it consistant with the client metrics which is messaging.client.sent.messages etc as well as the third example.

Note I don't think the kestrel example applies here as kestrel can only be server side app which is not the case for ActiveMQ.

The way I look at it the last segment of the metric name should be the unit when without the name wouldn't be clear. This matches:

Units do not need to be specified in the names since they are included during instrument creation, but can be added if there is ambiguity.

But yes I agree the documentation can be streamlined. Perhaps @trask can clarify what the naming intention is for these scenarios.