You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: specification/trace/semantic_conventions/messaging.md
+81-15Lines changed: 81 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,8 +16,10 @@
16
16
-[Messaging attributes](#messaging-attributes)
17
17
*[Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems)
18
18
+[RabbitMQ](#rabbitmq)
19
+
+[Apache Kafka](#apache-kafka)
19
20
-[Examples](#examples)
20
21
*[Topic with multiple consumers](#topic-with-multiple-consumers)
22
+
*[Apache Kafka Example](#apache-kafka-example)
21
23
*[Batch receiving](#batch-receiving)
22
24
*[Batch processing](#batch-processing)
23
25
@@ -27,18 +29,30 @@
27
29
28
30
Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS):
29
31
30
-
A *message* usually consists of headers (or properties, or meta information) and an optional body. It is sent by a single message *producer* to:
32
+
A *message* is an envelope with a potentially empty payload.
33
+
This envelope may offer the possibility to convey additional metadata, often in key/value form.
31
34
32
-
* Physically: some message *broker* (which can be e.g., a single server, or a cluster, or a local process reached via IPC). The broker handles the actual routing, delivery, re-delivery, persistence, etc. In some messaging systems the broker may be identical or co-located with (some) message consumers.
35
+
A message is sent by a message *producer* to:
36
+
37
+
* Physically: some message *broker* (which can be e.g., a single server, or a cluster, or a local process reached via IPC). The broker handles the actual delivery, re-delivery, persistence, etc. In some messaging systems the broker may be identical or co-located with (some) message consumers.
38
+
With Apache Kafka, the physical broker a message is written to depends on the number of partitions, and which broker is the *leader* of the partition the record is written to.
33
39
* Logically: some particular message *destination*.
34
40
41
+
Messages can be delivered to 0, 1, or multiple consumers depending on the dispatching semantic of the protocol.
42
+
35
43
### Destinations
36
44
37
-
A destination is usually identified by some name unique within the messaging system instance, which might look like an URL or a simple one-word identifier.
38
-
Two kinds of destinations are distinguished: *topic*s and *queue*s.
39
-
A message that is sent (the send-operation is often called "*publish*" in this context) to a *topic* is broadcasted to all *subscribers* of the topic.
45
+
A destination is usually identified by some name unique within the messaging system instance, which might look like a URL or a simple one-word identifier.
46
+
Traditional messaging, such as JMS, involves two kinds of destinations: *topic*s and *queue*s.
47
+
A message that is sent (the send-operation is often called "*publish*" in this context) to a *topic* is broadcasted to all consumers that have *subscribed* to the topic.
40
48
A message submitted to a queue is processed by a message *consumer* (usually exactly once although some message systems support a more performant at-least-once mode for messages with [idempotent][] processing).
41
49
50
+
In a messaging system such as Apache Kafka, all destinations are *topic*s.
51
+
Each record, or message, is sent to a single consumer per consumer group.
52
+
Consumer groups provide *deliver once* semantics for consumers of a topic within a group.
53
+
Whether a specific message is processed as if it was sent to a topic or queue entirely depends on the consumer groups and their composition.
54
+
For instance, there can be multiple consumer groups processing records from the same topic.
@@ -47,11 +61,10 @@ The consumption of a message can happen in multiple steps.
47
61
First, the lower-level receiving of a message at a consumer, and then the logical processing of the message.
48
62
Often, the waiting for a message is not particularly interesting and hidden away in a framework that only invokes some handler function to process a message once one is received
49
63
(in the same way that the listening on a TCP port for an incoming HTTP message is not particularly interesting).
50
-
However, in a synchronous conversation, the wait time for a message is important.
51
64
52
65
### Conversations
53
66
54
-
In some messaging systems, a message can receive a reply message that answers a particular other message that was sent earlier. All messages that are grouped together by such a reply-relationship are called a *conversation*.
67
+
In some messaging systems, a message can receive one or more reply messages that answers a particular other message that was sent earlier. All messages that are grouped together by such a reply-relationship are called a *conversation*.
55
68
The grouping usually happens through some sort of "In-Reply-To:" meta information or an explicit *conversation ID* (sometimes called *correlation ID*).
56
69
Sometimes a conversation can span multiple message destinations (e.g. initiated via a topic, continued on a temporary one-to-one queue).
57
70
@@ -74,6 +87,7 @@ The span name SHOULD be set to the message destination name and the operation be
74
87
75
88
The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](../api.md#span)).
76
89
This can be assumed if it is statically derived from application code or configuration.
90
+
Wherever possible, the real destination names after resolving logical or aliased names SHOULD be used.
77
91
If the destination name is dynamic, such as a [conversation ID](#conversations) or a value obtained from a `Reply-To` header, it SHOULD NOT be used for the span name.
78
92
In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(temporary)"` for [temporary destinations](#temporary-destinations) SHOULD be used instead.
79
93
@@ -122,20 +136,19 @@ The following operations related to messages are defined for these semantic conv
122
136
|`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 |
123
137
|`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 |
124
138
|`messaging.message_payload_compressed_size_bytes`| number | The compressed size of the message payload in bytes. |`2048`| No |
139
+
|[`net.peer.ip`](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`| Conditional<br>If available. |
140
+
|[`net.peer.name`](span-general.md)| string | Remote hostname or similar, see note below. [2]|`example.com`| Conditional<br>If available. |
125
141
126
142
**[1]:** Required only if the message destination is either a `queue` or `topic`.
127
143
128
-
**Additional attribute requirements:** At least one of the following sets of attributes is required:
129
-
130
-
*[`net.peer.name`](span-general.md)
131
-
*[`net.peer.ip`](span-general.md)
144
+
**[2]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
132
145
133
146
`messaging.destination_kind` MUST be one of the following:
134
147
135
148
| Value | Description |
136
149
|---|---|
137
150
|`queue`| A message sent to a queue |
138
-
|`topic`| A message broadcasted to the subscribers of the topic |
151
+
|`topic`| A message sent to a topic |
139
152
<!-- endsemconv -->
140
153
141
154
Additionally `net.peer.port` from the [network attributes][] is recommended.
@@ -176,6 +189,26 @@ In RabbitMQ, the destination is defined by an _exchange_ and a _routing key_.
176
189
`messaging.destination` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.
177
190
The routing key MUST be provided to the attribute `messaging.rabbitmq.routing_key`, unless it is empty.
178
191
192
+
#### Apache Kafka
193
+
194
+
For Apache Kafka, the following additional attributes are defined:
195
+
196
+
<!-- semconv messaging.kafka -->
197
+
| Attribute | Type | Description | Example | Required |
198
+
|---|---|---|---|---|
199
+
|`messaging.kafka.message_key`| string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message_id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1]|`myKey`| No |
200
+
|`messaging.kafka.consumer_group`| string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. |`my-group`| No |
201
+
|`messaging.kafka.client_id`| string | Client Id for the Consumer or Producer that is handling the message. |`client-5`| No |
202
+
|`messaging.kafka.partition`| number | Partition the message is sent to. |`2`| No |
203
+
|`messaging.kafka.tombstone`| boolean | A boolean that is true if the message is a tombstone. || Conditional<br>If missing, it is assumed to be false. |
204
+
205
+
**[1]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
206
+
<!-- endsemconv -->
207
+
208
+
For Apache Kafka producers, [`peer.service`](./span-general.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to.
209
+
The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service.
210
+
If an intermediary broker is present, `service.name` and `peer.service` will not be the same.
Given is a process P, that sends two messages to a queue Q on messaging system MS, and a process C, which receives both of them in one batch (Span Recv1) and processes each message separately (Spans Proc1 and Proc2).
0 commit comments