Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Messaging-System Metric semantic conventions #1077

Closed
wants to merge 14 commits into from
Closed

Messaging-System Metric semantic conventions #1077

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
828c7d5
Initial semantic conventions for messaging metrics. #1014
cwildman Oct 7, 2020
edf4012
Use span kind in metric naming.
cwildman Oct 8, 2020
aa439d0
Attempt to use the semconv yaml format and generator.
cwildman Oct 8, 2020
56cdbcb
Add metrics for batching.
cwildman Oct 8, 2020
78e7612
Update changelog.
cwildman Oct 9, 2020
19f9623
Make duration metrics more clear.
cwildman Oct 12, 2020
b21f5a7
Switch to use references instead of constraints for net labels.
cwildman Oct 13, 2020
3353e68
Change wording of description on Counters.
cwildman Oct 13, 2020
182f261
Add received to consumer metrics to differentiate from processing.
cwildman Oct 13, 2020
683200f
Use references for metrics-messaging labels.
cwildman Oct 13, 2020
6041dc6
Remove redundant counters.
cwildman Oct 15, 2020
c573be5
Fix lint errors.
cwildman Oct 19, 2020
dc5c766
Fix table formatting.
cwildman Oct 19, 2020
8683a2a
PR feedback.
cwildman Nov 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ release.

New:

- Add semantic conventions for messaging system metrics.
([#1077](https://github.com/open-telemetry/opentelemetry-specification/pull/1077))
- Add performance benchmark specification
([#748](https://github.com/open-telemetry/opentelemetry-specification/pull/748))
- Enforce that the Baggage API must be fully functional, even without an installed SDK.
Expand Down
21 changes: 21 additions & 0 deletions semantic_conventions/metrics/messaging.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
groups:
- id: metrics-messaging
prefix: messaging
brief: >
This document defines the attributes used in
messaging system metric instruments.
attributes:
- ref: messaging.system
required: always
- ref: messaging.destination
required: always
- ref: messaging.destination_kind
required: always
- ref: messaging.temp_destination
- ref: messaging.protocol
- ref: messaging.protocol_version
- ref: messaging.url
- ref: net.peer.name
- ref: net.peer.ip
- ref: net.peer.port
- ref: net.transport
92 changes: 92 additions & 0 deletions specification/metrics/semantic_conventions/messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Semantic conventions for messaging systems

The conventions described in this section are specific to messaging systems. When interactions with messaging systems occur,
metric events about those operations will be generated and reported, providing insight into those
operations.

**Disclaimer:** These are initial messaging system metric instruments and labels, more may be added
in the future.

## Definitions

The [Trace Messaging Semantic Conventions Definitions](../../trace/semantic_conventions/messaging.md#definitions) is a resource for the messaging system terminology used in this document.

## Common Labels

The following labels SHOULD be applied to all messaging metric instruments.

<!-- semconv metrics-messaging -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| [`messaging.destination`](../../trace/semantic_conventions/messaging.md) | string | The message destination name. This might be equal to the span name but is required nevertheless. | `MyQueue`<br>`MyTopic` | Yes |
| [`messaging.destination_kind`](../../trace/semantic_conventions/messaging.md) | string enum | The kind of message destination | `queue` | Yes |
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
| [`messaging.protocol`](../../trace/semantic_conventions/messaging.md) | string | The name of the transport protocol. | `AMQP`<br>`MQTT` | No |
| [`messaging.protocol_version`](../../trace/semantic_conventions/messaging.md) | string | The version of the transport protocol. | `0.9.1` | No |
| [`messaging.system`](../../trace/semantic_conventions/messaging.md) | string | A string identifying the messaging system. | `kafka`<br>`rabbitmq`<br>`activemq` | Yes |
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
| [`messaging.temp_destination`](../../trace/semantic_conventions/messaging.md) | boolean | A boolean that is true if the message destination is temporary. | | No |
| [`messaging.url`](../../trace/semantic_conventions/messaging.md) | string | Connection string. | `tibjmsnaming://localhost:7222`<br>`https://queue.amazonaws.com/80398EXAMPLE/MyQueue` | No |
| [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No |
| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | No |
| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | number | Remote port number. | `80`<br>`8080`<br>`443` | No |
| [`net.transport`](../../trace/semantic_conventions/span-general.md) | string enum | Transport protocol used. See note below. | `IP.TCP` | No |
<!-- endsemconv -->

For messaging system metric event labels, one of the following sets of labels is RECOMMENDED (in order of usual preference unless for a particular messaging system it is known that some other set is preferable for some reason; all strings must be non-empty):

* `messaging.url`
* `net.peer.name`, `net.peer.port`, `net.peer.ip`, `net.transport`

## Send Message Metric Instruments

The following metric instruments SHOULD be used to capture metric events for every message send operation
unless the producer is batching. If the producer is batching any metric instruments
within this section MAY be omitted.

| Name | Instrument | Units | Description |
|----------------------|---------------|--------------|-------------|
| `messaging.producer.duration` | ValueRecorder | milliseconds | Time spent producing a message to a queue/topic. |
| `messaging.producer.bytes` | ValueRecorder | bytes | The (uncompressed) size of the payload sent in bytes. Also use this metric instrument if it is unknown whether the compressed or uncompressed payload size is reported. |
| `messaging.producer.compressed.bytes` | ValueRecorder | bytes | The compressed size of the payload sent in bytes. |

### Send Batch Metric Instruments

When a message system uses batching the following metric instruments SHOULD
be used to capture metric events for every batch send operation.

| Name | Instrument | Units | Description |
|----------------------|---------------|--------------|-------------|
| `messaging.producer.batch.duration` | ValueRecorder | milliseconds | Time spent producing a batch of messages to a queue/topic. |
| `messaging.producer.batch.size` | ValueRecorder | messages | The number of messages in each batch if this producer/client is batching messages. |
| `messaging.producer.batch.bytes` | ValueRecorder | bytes | The (uncompressed) size of the batch sent in bytes. Also use this metric instrument if it is unknown whether the compressed or uncompressed batch size is reported. |
| `messaging.producer.batch.compressed.bytes` | ValueRecorder | bytes | The compressed size of the batch sent in bytes. |

## Receive Message Metric Instruments

The following metric instruments SHOULD be used to capture metric events for every message receive operation
unless the consumer is receiving batches. If the consumer is receiving batches any metric instruments within this section MAY be omitted.

| Name | Instrument | Units | Description |
|----------------------|---------------|--------------|-------------|
| `messaging.consumer.received.duration` | ValueRecorder | milliseconds | Time spent receiving a message from a queue/topic. |
| `messaging.consumer.received.bytes` | ValueRecorder | bytes | The (uncompressed) size of the message received in bytes. Also use this metric instrument if it is unknown whether the compressed or uncompressed payload size is reported. |
| `messaging.consumer.received.compressed.bytes` | ValueRecorder | bytes | The compressed size of the payload sent in bytes. |

### Receive Batch Metric Instruments

When a message system uses batching the following metric instruments SHOULD
be used to capture metric events for every batch receive operation.

| Name | Instrument | Units | Description |
|----------------------|---------------|--------------|-------------|
| `messaging.consumer.received.batch.duration` | ValueRecorder | milliseconds | Time spent receiving a batch of messages from a queue/topic. |
| `messaging.consumer.received.batch.size` | ValueRecorder | messages | The number of messages in each batch if messages are consumed in batches. |
| `messaging.consumer.received.batch.bytes` | ValueRecorder | bytes | The (uncompressed) size of the batch received in bytes. Also use this metric instrument if it is unknown whether the compressed or uncompressed batch size is reported. |
| `messaging.consumer.received.batch.compressed.bytes` | ValueRecorder | bytes | The compressed size of the batch received in bytes. |

## Process Message Metric Instruments

The following metric instruments SHOULD be used to capture metric events for every message processing operation.

| Name | Instrument | Units | Description |
|----------------------|---------------|--------------|-------------|
| `messaging.consumer.processed.duration` | ValueRecorder | milliseconds | Time spent processing a message. |