140 lines
10 KiB
Markdown
140 lines
10 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: RabbitMQ
|
|
--->
|
|
|
|
# Semantic Conventions for RabbitMQ
|
|
|
|
**Status**: [Experimental][DocumentStatus]
|
|
|
|
The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md).
|
|
|
|
> [!Warning]
|
|
>
|
|
> Existing messaging instrumentations that are using
|
|
> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md)
|
|
> (or prior):
|
|
>
|
|
> * SHOULD NOT change the version of the messaging conventions that they emit by default
|
|
> until the messaging semantic conventions are marked stable.
|
|
> Conventions include, but are not limited to, attributes,
|
|
> metric and span names, span kind and unit of measure.
|
|
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
|
|
> in the existing major version which is a comma-separated list of values.
|
|
> The list of values includes:
|
|
> * `messaging` - emit the new, stable messaging conventions,
|
|
> and stop emitting the old experimental messaging conventions
|
|
> that the instrumentation emitted previously.
|
|
> * `messaging/dup` - emit both the old and the stable messaging conventions,
|
|
> allowing for a seamless transition.
|
|
> * The default behavior (in the absence of one of these values) is to continue
|
|
> emitting whatever version of the old experimental messaging conventions
|
|
> the instrumentation was emitting previously.
|
|
> * Note: `messaging/dup` has higher precedence than `messaging` in case both values are present
|
|
> * SHOULD maintain (security patching at a minimum) the existing major version
|
|
> for at least six months after it starts emitting both sets of conventions.
|
|
> * SHOULD drop the environment variable in the next major version.
|
|
> * SHOULD emit the new, stable values for span name, span kind and similar "single"
|
|
> valued concepts when `messaging/dup` is present in the list.
|
|
|
|
`messaging.system` MUST be set to `"rabbitmq"` and SHOULD be provided **at span creation time**.
|
|
|
|
## RabbitMQ attributes
|
|
|
|
In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
|
|
`messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.
|
|
|
|
<!-- semconv messaging.rabbitmq -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` |  |
|
|
| [`error.type`](/docs/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` If and only if the messaging operation has failed. |  |
|
|
| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] |  |
|
|
| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `create`; `send`; `receive` | `Conditionally Required` If applicable. |  |
|
|
| [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. |  |
|
|
| [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. |  |
|
|
| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. |  |
|
|
| [`messaging.message.conversation_id`](/docs/attributes-registry/messaging.md) | string | Message [correlation Id](https://www.rabbitmq.com/tutorials/tutorial-six-java#correlation-id) property. | `MyConversationId` | `Recommended` |  |
|
|
| [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. |  |
|
|
| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. [6] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
|
| [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` |  |
|
|
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` |  |
|
|
| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [8] | `1439` | `Opt-In` |  |
|
|
|
|
**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
|
|
|
|
When `error.type` is set to a type (e.g., an exception type), its
|
|
canonical class name identifying the type within the artifact SHOULD be used.
|
|
|
|
Instrumentations SHOULD document the list of errors they report.
|
|
|
|
The cardinality of `error.type` within one instrumentation library SHOULD be low.
|
|
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
|
|
should be prepared for `error.type` to have high cardinality at query time when no
|
|
additional filters are applied.
|
|
|
|
If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
|
|
|
|
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
|
|
it's RECOMMENDED to:
|
|
|
|
- Use a domain-specific attribute
|
|
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
|
|
|
|
**[2] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If
|
|
the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker.
|
|
|
|
**[3] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch.
|
|
|
|
**[4] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality.
|
|
|
|
**[5] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
|
|
|
|
**[6] `network.peer.address`:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
|
|
|
|
**[7] `server.port`:** 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.
|
|
|
|
**[8] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
|
|
body size should be used.
|
|
|
|
The following attributes can be important for making sampling decisions
|
|
and SHOULD be provided **at span creation time** (if provided at all):
|
|
|
|
* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
|
|
* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
|
|
* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
|
|
* [`server.address`](/docs/attributes-registry/server.md)
|
|
* [`server.port`](/docs/attributes-registry/server.md)
|
|
|
|
---
|
|
|
|
`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 | Stability |
|
|
|---|---|---|
|
|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
|
|
|
|
---
|
|
|
|
`messaging.operation.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 | Stability |
|
|
|---|---|---|
|
|
| `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 sending scenarios. |  |
|
|
| `process` | One or more messages are processed by a consumer. |  |
|
|
| `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. |  |
|
|
| `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. |  |
|
|
| `settle` | One or more messages are settled. |  |
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|