diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml new file mode 100644 index 000000000..f3934b355 --- /dev/null +++ b/semantic_conventions/trace/messaging.yaml @@ -0,0 +1,116 @@ +groups: + - id: messaging + prefix: messaging + brief: > + This document defines the attributes used in + messaging systems. + attributes: + - id: system + type: string + required: always + brief: 'A string identifying the messaging system.' + examples: ['kafka', 'rabbitmq', 'activemq'] + - id: destination + type: string + required: always + brief: > + The message destination name. This might be equal to the span name + but is required nevertheless. + examples: ['MyQueue', 'MyTopic'] + - id: destination_kind + type: + allow_custom_values: false + members: + - id: queue + value: "queue" + brief: "A message sent to a queue" + - id: topic + value: "topic" + brief: "A message broadcasted to the subscribers of the topic" + required: + conditional: 'Required only if the message destination is either a `queue` or `topic`.' + brief: 'The kind of message destination' + - id: temp_destination + type: boolean + required: + conditional: 'If missing, it is assumed to be false.' + brief: 'A boolean that is true if the message destination is temporary.' + - id: protocol + type: string + brief: 'The name of the transport protocol.' + examples: ['AMQP', 'MQTT'] + - id: protocol_version + type: string + brief: 'The version of the transport protocol.' + examples: '0.9.1' + - id: url + type: string + brief: 'Connection string.' + examples: ['tibjmsnaming://localhost:7222', 'https://queue.amazonaws.com/80398EXAMPLE/MyQueue'] + - id: message_id + type: string + brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' + examples: '452a7c7c7c7048c2f887f61572b18fc2' + - id: conversation_id + type: string + brief: > + The [conversation ID](#conversations) identifying the conversation to which the message belongs, + represented as a string. Sometimes called "Correlation ID". + examples: 'MyConversationId' + - id: message_payload_size_bytes + type: number + brief: > + The (uncompressed) size of the message payload in bytes. + Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. + examples: 2738 + - id: message_payload_compressed_size_bytes + type: number + brief: 'The compressed size of the message payload in bytes.' + examples: 2048 + constraints: + - any_of: + - 'net.peer.name' + - 'net.peer.ip' + - include: network + + - id: messaging.producer + prefix: messaging + extends: messaging + span_kind: producer + brief: 'Semantic convention for producers of messages sent to a messaging systems.' + + - id: messaging.producer.synchronous + prefix: messaging + extends: messaging + span_kind: client + brief: > + Semantic convention for clients of messaging systems that produce messages + and synchronously wait for responses. + + - id: messaging.consumer + prefix: messaging + extends: messaging + span_kind: consumer + brief: 'Semantic convention for a consumer of messages received from a messaging system' + attributes: + - id: operation + type: + allow_custom_values: false + members: + - id: receive + value: "receive" + - id: process + value: "process" + brief: > + A string identifying the kind of message consumption as defined in the + [Operation names](#operation-names) section above. + If the operation is "send", this attribute MUST NOT be set, since the + operation can be inferred from the span kind in that case. + + - id: messaging.consumer.synchronous + prefix: messaging + extends: messaging.consumer + span_kind: server + brief: > + Semantic convention for servers that consume messages received from messaging systems + and always send back replies directed to the producers of these messages. diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 2b627c7ad..b133f5929 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -108,21 +108,37 @@ The following operations related to messages are defined for these semantic conv ## Messaging attributes -| Attribute name | Notes and examples | Required? | -| -------------- | ---------------------------------------------------------------------- | --------- | -| `messaging.system` | A string identifying the messaging system such as `kafka`, `rabbitmq` or `activemq`. | Yes | -| `messaging.destination` | The message destination name, e.g. `MyQueue` or `MyTopic`. This might be equal to the span name but is required nevertheless. | Yes | -| `messaging.destination_kind` | The kind of message destination: Either `queue` or `topic`. | Yes, if either of them applies. | -| `messaging.temp_destination` | A boolean that is `true` if the message destination is [temporary](#temporary-destinations). | If temporary (assumed to be `false` if missing). | -| `messaging.protocol` | The name of the transport protocol such as `AMQP` or `MQTT`. | No | -| `messaging.protocol_version` | The version of the transport protocol such as `0.9.1`. | No | -| `messaging.url` | Connection string such as `tibjmsnaming://localhost:7222` or `https://queue.amazonaws.com/80398EXAMPLE/MyQueue`. | No | -| `messaging.message_id` | A value used by the messaging system as an identifier for the message, represented as a string. | No | -| `messaging.conversation_id` | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | No | -| `messaging.message_payload_size_bytes` | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | No | -| `messaging.message_payload_compressed_size_bytes` | The compressed size of the message payload in bytes. | No | + +| Attribute | Type | Description | Example | Required | +|---|---|---|---|---| +| `messaging.system` | string | A string identifying the messaging system. | `kafka`
`rabbitmq`
`activemq` | Yes | +| `messaging.destination` | string | The message destination name. This might be equal to the span name but is required nevertheless. | `MyQueue`
`MyTopic` | Yes | +| `messaging.destination_kind` | string enum | The kind of message destination | `queue` | Conditional [1] | +| `messaging.temp_destination` | boolean | A boolean that is true if the message destination is temporary. | | Conditional
If missing, it is assumed to be false. | +| `messaging.protocol` | string | The name of the transport protocol. | `AMQP`
`MQTT` | No | +| `messaging.protocol_version` | string | The version of the transport protocol. | `0.9.1` | No | +| `messaging.url` | string | Connection string. | `tibjmsnaming://localhost:7222`
`https://queue.amazonaws.com/80398EXAMPLE/MyQueue` | No | +| `messaging.message_id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | No | +| `messaging.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | No | +| `messaging.message_payload_size_bytes` | number | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | No | +| `messaging.message_payload_compressed_size_bytes` | number | The compressed size of the message payload in bytes. | `2048` | No | -Additionally at least one of `net.peer.name` or `net.peer.ip` from the [network attributes][] is required and `net.peer.port` is recommended. +**[1]:** Required only if the message destination is either a `queue` or `topic`. + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* [`net.peer.name`](span-general.md) +* [`net.peer.ip`](span-general.md) + +`messaging.destination_kind` MUST be one of the following: + +| Value | Description | +|---|---| +| `queue` | A message sent to a queue | +| `topic` | A message broadcasted to the subscribers of the topic | + + +Additionally `net.peer.port` from the [network attributes][] is recommended. Furthermore, it is strongly recommended to add the [`net.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). These attributes should be set to the broker to which the message is sent/from which it is received. @@ -132,9 +148,18 @@ These attributes should be set to the broker to which the message is sent/from w For message consumers, the following additional attributes may be set: -| Attribute name | Notes and examples | Required? | -| -------------- | ---------------------------------------------------------------------- | --------- | -| `messaging.operation` | A string identifying the kind of message consumption as defined in the [Operation names](#operation-names) section above. Only `"receive"` and `"process"` are used for this attribute. If the operation is `"send"`, this attribute MUST NOT be set, since the operation can be inferred from the span kind in that case. | No | + +| Attribute | Type | Description | Example | Required | +|---|---|---|---|---| +| `messaging.operation` | string enum | A string identifying the kind of message consumption as defined in the [Operation names](#operation-names) section above. If the operation is "send", this attribute MUST NOT be set, since the operation can be inferred from the span kind in that case. | `receive` | No | + +`messaging.operation` MUST be one of the following: + +| Value | Description | +|---|---| +| `receive` | receive | +| `process` | process | + The _receive_ span is be used to track the time used for receiving the message(s), whereas the _process_ span(s) track the time for processing the message(s). Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`.