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

Separate messaging.system values from the spec #669

Closed
wants to merge 2 commits into from
+140 −107
Closed

Separate messaging.system values from the spec #669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
477ee4c
separate messaging.system values
lmolkova Jan 25, 2024
a683c6d
Alternative upproach: extending enum
lmolkova Jan 27, 2024
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
19 changes: 3 additions & 16 deletions docs/attributes-registry/messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [6] | `2738` |
| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` |
| `messaging.operation` | string | A string identifying the kind of messaging operation. [7] | `publish` |
| `messaging.system` | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` |
| `messaging.system` | string | An identifier for the messaging system being used. [8] | `kafka`; `rabbitmq` |

**[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs.

Expand All @@ -51,6 +51,8 @@ size should be used.

**[7]:** If a custom value is used, it MUST be of low cardinality.

**[8]:** Messaging instrumentations MUST use applicable value from the [list of known messaging systems](/docs/messaging/README.md#technology-specific-semantic-conventions) when it is available. When instrumenting a new messaging system, instrumentation authors should document the new system name and add it to the [list](/docs/messaging/README.md#technology-specific-semantic-conventions).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New identifiers for messaging systems shouldn't be added to the README, but to the YAML files.


`messaging.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
Expand All @@ -59,21 +61,6 @@ size should be used.
| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. |
| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. |
| `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. |

`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `activemq` | Apache ActiveMQ |
| `aws_sqs` | Amazon Simple Queue Service (SQS) |
| `azure_eventgrid` | Azure Event Grid |
| `azure_eventhubs` | Azure Event Hubs |
| `azure_servicebus` | Azure Service Bus |
| `gcp_pubsub` | Google Cloud Pub/Sub |
| `jms` | Java Message Service |
| `kafka` | Apache Kafka |
| `rabbitmq` | RabbitMQ |
| `rocketmq` | Apache RocketMQ |
<!-- endsemconv -->

## GCP Pub/Sub Attributes
Expand Down
12 changes: 6 additions & 6 deletions docs/faas/aws-lambda.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,8 @@ added as a link to the span. This means the span may have as many links as messa
See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.

- [`faas.trigger`][faas] MUST be set to `pubsub`.
- [`messaging.operation`](/docs/messaging/messaging-spans.md) MUST be set to `process`.
- [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `AmazonSQS`.
- [`messaging.operation`](/docs/messaging/messaging-spans.md) MUST be set to `deliver`.
- [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `aws_sqs`.

### SQS Message

Expand All @@ -159,8 +159,8 @@ added as a link to the span.
See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.

- [`faas.trigger`][faas] MUST be set to `pubsub`.
- [`messaging.operation`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`.
- [`messaging.system`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `AmazonSQS`.
- [`messaging.operation`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `deliver`.
- [`messaging.system`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `aws_sqs`.

Other [Messaging attributes](/docs/messaging/messaging-spans.md#messaging-attributes) SHOULD be set based on the available information in the SQS message
event.
Expand Down Expand Up @@ -239,9 +239,9 @@ Function F: | Span ProcBatch |
| Links | | | | Span Prod1 | Span Prod2 |
| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` |
| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` |
| `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` |
| `messaging.system` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` | `aws_sqs` |
| `messaging.destination.name` | `Q` | `Q` | `Q` | `Q` | `Q` |
| `messaging.operation` | | | `process` | `process` | `process` |
| `messaging.operation` | `publish` | `publish` | `deliver` | `deliver` | `deliver` |
| `messaging.message.id` | | | | `"a1"` | `"a2"` |

Note that if Span Prod1 and Span Prod2 were sent to different queues, Span ProcBatch would not have
Expand Down
28 changes: 23 additions & 5 deletions docs/messaging/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,29 @@ Semantic conventions for messaging systems are defined for the following signals
* [Messaging Spans](messaging-spans.md): Semantic Conventions for messaging *spans*.
* [Messaging Metrics](messaging-metrics.md): Semantic Conventions for messaging *metrics*.

Technology specific semantic conventions are defined for the following messaging systems:
## Technology specific semantic conventions

* [Kafka](kafka.md): Semantic Conventions for *Apache Kafka*.
* [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*.
* [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*.
* [Google Cloud Pub/Sub](gcp-pubsub.md): Semantic Conventions for *Google Cloud Pub/Sub*.
**Status**: [Experimental][DocumentStatus]
<!-- Individual messaging systems may be declared stable along with the corresponding messaging.system value, but this list as a whole is not intended to be stabilized. -->

Messaging system name is recorded on telemetry signals with `messaging.system` attribute.

`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used.

<!-- TODO this could be auto-generated if is implemented https://github.com/open-telemetry/build-tools/issues/192 -->
| Value | Description | Semantic Conventions |
|---|---|---|
| `activemq` | Apache ActiveMQ | |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | |
| `azure_eventgrid` | Azure Event Grid | |
| `azure_eventhubs` | Azure Event Hubs | |
| `azure_servicebus` | Azure Service Bus | |
| `gcp_pubsub` | Google Cloud Pub/Sub | [Google Cloud Pub/Sub](gcp-pubsub.md) |
| `jms` | Java Message Service |
| `kafka` | Apache Kafka | [Kafka](kafka.md)|
| `rabbitmq` | RabbitMQ | [RabbitMQ](rabbitmq.md) |
| `rocketmq` | Apache RocketMQ | [RocketMQ](rocketmq.md) |

If none of these values apply, consider submitting a proposal to this specification to add a new system.

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
37 changes: 12 additions & 25 deletions docs/messaging/messaging-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ All messaging metrics share the same set of attributes:
| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: [2] |
| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] |
| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. |
| [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required |
| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Conditionally Required: [7] |
| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [8] | `3.1.1` | Recommended |
| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | Recommended |
| [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. [6] | `kafka`; `rabbitmq` | Required |
| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [7] | `amqp`; `mqtt` | Conditionally Required: [8] |
| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [9] | `3.1.1` | Recommended |
| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [11] | `80`; `8080`; `443` | Recommended |

**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
Expand All @@ -59,36 +59,23 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi

**[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.

**[6]:** The value SHOULD be normalized to lowercase.
**[6]:** Messaging instrumentations MUST use applicable value from the [list of known messaging systems](/docs/messaging/README.md#technology-specific-semantic-conventions) when it is available. When instrumenting a new messaging system, instrumentation authors should document the new system name and add it to the [list](/docs/messaging/README.md#technology-specific-semantic-conventions).

**[7]:** Only for messaging systems and frameworks that support more than one protocol.
**[7]:** The value SHOULD be normalized to lowercase.

**[8]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[8]:** Only for messaging systems and frameworks that support more than one protocol.

**[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[9]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.

**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
**[10]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.

**[11]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.

`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |

`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `activemq` | Apache ActiveMQ |
| `aws_sqs` | Amazon Simple Queue Service (SQS) |
| `azure_eventgrid` | Azure Event Grid |
| `azure_eventhubs` | Azure Event Hubs |
| `azure_servicebus` | Azure Service Bus |
| `gcp_pubsub` | Google Cloud Pub/Sub |
| `jms` | Java Message Service |
| `kafka` | Apache Kafka |
| `rabbitmq` | RabbitMQ |
| `rocketmq` | Apache RocketMQ |
<!-- endsemconv -->

## Producer metrics
Expand Down
Loading
Loading