Skip to content

Commit cd9d5db

Browse files
pyohannespyohannes
committed
Unify process and deliver operations
1 parent 108547b commit cd9d5db

File tree

3 files changed

+34
-77
lines changed

3 files changed

+34
-77
lines changed

‎docs/messaging/messaging-metrics.md

+7-33
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
- [Consumer metrics](#consumer-metrics)
1414
* [Metric: `messaging.receive.duration`](#metric-messagingreceiveduration)
1515
* [Metric: `messaging.receive.messages`](#metric-messagingreceivemessages)
16-
* [Metric: `messaging.deliver.duration`](#metric-messagingdeliverduration)
17-
* [Metric: `messaging.deliver.messages`](#metric-messagingdelivermessages)
16+
* [Metric: `messaging.process.duration`](#metric-messagingprocessduration)
17+
* [Metric: `messaging.process.messages`](#metric-messagingprocessmessages)
1818

1919
<!-- tocstop -->
2020

@@ -151,37 +151,9 @@ _Note: The need to report `messaging.receive.messages` depends on the messaging
151151
| `messaging.receive.messages` | Counter | `{message}` | Measures the number of received messages. |
152152
<!-- endsemconv -->
153153

154-
### Metric: `messaging.deliver.duration`
155-
156-
This metric is [required][MetricRequired] for operations are not initiated by the application code (push-based deliver).
157-
158-
When this metric is reported alongside a messaging deliver span, the metric value SHOULD be the same as the corresponding span duration.
159-
160-
This metric SHOULD be specified with
161-
[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice)
162-
of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
163-
164-
<!-- semconv metric.messaging.deliver.duration(metric_table) -->
165-
| Name | Instrument Type | Unit (UCUM) | Description |
166-
| -------- | --------------- | ----------- | -------------- |
167-
| `messaging.deliver.duration` | Histogram | `s` | Measures the duration of deliver operation. |
168-
<!-- endsemconv -->
169-
170-
### Metric: `messaging.deliver.messages`
171-
172-
This metric is [required][MetricRequired] for batch delivery operations. It's [opt-in][MetricOptIn] when the messaging system does not support batch delivery since the message count can be derived from the `messaging.deliver.duration` histogram.
173-
174-
_Note: The need to report `messaging.deliver.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._
175-
176-
<!-- semconv metric.messaging.deliver.messages(metric_table) -->
177-
| Name | Instrument Type | Unit (UCUM) | Description |
178-
| -------- | --------------- | ----------- | -------------- |
179-
| `messaging.deliver.messages` | Counter | `{message}` | Measures the number of delivered messages. |
180-
<!-- endsemconv -->
181-
182154
### Metric: `messaging.process.duration`
183155

184-
This metric is [recommended][MetricRecommended] for processing operations that are initiated by application code.
156+
This metric is [required][MetricRequired] for operations are not initiated by the application code (push-based deliver), and [recommended](MetricRecommended) for processing operations instrumented for pull-based scenarios.
185157

186158
When this metric is reported alongside a messaging process span, the metric value SHOULD be the same as the corresponding span duration.
187159

@@ -192,12 +164,14 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
192164
<!-- semconv metric.messaging.process.duration(metric_table) -->
193165
| Name | Instrument Type | Unit (UCUM) | Description |
194166
| -------- | --------------- | ----------- | -------------- |
195-
| `messaging.process.duration` | Histogram | `s` | Measures the duration of process operation. |
167+
| `messaging.process.duration` | Histogram | `s` | Measures the duration of the process operation. |
196168
<!-- endsemconv -->
197169

198170
### Metric: `messaging.process.messages`
199171

200-
This metric is [recommended][MetricRecommended] for batch process operations.
172+
This metric is [required][MetricRequired] for batch process operations, and [recommended](MetricRecommended) for batch processing operations instrumented for pull-based scenarios. It's [opt-in][MetricOptIn] when the messaging system does not support batch processing since the message count can be derived from the `messaging.process.duration` histogram.
173+
174+
_Note: The need to report `messaging.process.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._
201175

202176
<!-- semconv metric.messaging.process.messages(metric_table) -->
203177
| Name | Instrument Type | Unit (UCUM) | Description |

‎docs/messaging/messaging-spans.md

+27-28
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ Examples:
191191
* `shop.orders receive`
192192
* `shop.orders settle`
193193
* `print_jobs publish`
194-
* `topic with spaces deliver`
194+
* `topic with spaces process`
195195
* `AuthenticationRequest-Conversations settle`
196196
* `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination)
197197

@@ -206,8 +206,7 @@ The following operations related to messages are defined for these semantic conv
206206
| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. |
207207
| `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. |
208208
| `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. |
209-
| `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. |
210-
| `process` | One or more messages are processed by consumer. |
209+
| `process` | One or more messages are delivered to or processed by a consumer. |
211210
| `settle` | One or more messages are settled. |
212211

213212
### Span kind
@@ -220,7 +219,7 @@ SHOULD be set according to the following table, based on the operation a span de
220219
| `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. |
221220
| `create` | `PRODUCER` |
222221
| `receive` | `CONSUMER` |
223-
| `deliver` | `CONSUMER` |
222+
| `process` | `CONSUMER` for push-based scenarios where no `receive` span exists. |
224223

225224
For cases not covered by the table above, the span kind should be set according
226225
to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#spankind),
@@ -254,29 +253,28 @@ message.
254253

255254
#### Consumer spans
256255

257-
"Deliver" spans SHOULD be created for operations of passing messages to the
258-
application when those operations are not initiated by the application code
259-
(push-based scenarios). A "Deliver" span covers the duration of such an
260-
operation, which is usually a callback or handler.
261-
262256
"Receive" spans SHOULD be created for operations of passing messages to the
263257
application when those operations are initiated by the application code
264258
(pull-based scenarios).
265259

266-
"Deliver" or "Receive" spans MUST NOT be created for messages that are
260+
"Process" spans SHOULD be created for operations of passing messages to the
261+
application when those operations are not initiated by the application code
262+
(push-based scenarios). Such "Process" span covers the duration of such an
263+
operation, which is usually a callback or handler.
264+
265+
"Process" spans MAY be created in addition to "Receive" spans for pull-based
266+
scenarios for operations of processing messages. Such spans could be created by
267+
application code, or by abstraction layers built on top of messaging SDKs.
268+
269+
"Receive" or "Process" spans MUST NOT be created for messages that are
267270
pre-fetched or cached by messaging libraries or SDKs until they are forwarded
268271
to the caller.
269272

270-
A single "Deliver" or "Receive" span can account for a single message, for a
273+
A single "Process" or "Receive" span can account for a single message, for a
271274
batch of messages, or for no message at all (if it is signalled that no
272-
messages were received). For each message it accounts for, the "Deliver" or
275+
messages were received). For each message it accounts for, the "Process" or
273276
"Receive" span SHOULD link to the message's creation context.
274277

275-
"Process" spans MAY be created in addition to "Deliver" and "Receive" spans,
276-
for operations of processing a single message or a batch of messages. For each
277-
message it accounts for, the "Process" span MAY link to the creation context of
278-
the message.
279-
280278
"Settle" spans SHOULD be created for every manually or automatically triggered
281279
settlement operation. A single "Settle" span can account for a single message
282280
or for multiple messages (in case messages are passed for settling as batches).
@@ -392,12 +390,13 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
392390

393391
`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.
394392

395-
| Value | Description |
396-
|---|---|
397-
| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. |
398-
| `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. |
399-
| `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. |
400-
| `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. |
393+
| Operation name | Description |
394+
| -------------- | ----------- |
395+
| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. |
396+
| `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. |
397+
| `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. |
398+
| `process` | One or more messages are delivered to or processed by a consumer. |
399+
| `settle` | One or more messages are settled. |
401400

402401
`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.
403402

@@ -493,11 +492,11 @@ flowchart LR;
493492
end
494493
subgraph CONSUMER1
495494
direction TB
496-
R1[Span Deliver A 1]
495+
R1[Span Process A 1]
497496
end
498497
subgraph CONSUMER2
499498
direction TB
500-
R2[Span Deliver A 2]
499+
R2[Span Process A 2]
501500
end
502501
P-. link .-R1;
503502
P-. link .-R2;
@@ -507,9 +506,9 @@ flowchart LR;
507506
linkStyle 0,1 color:green,stroke:green
508507
```
509508

510-
| Field or Attribute | Span Publish A | Span Deliver A 1| Span Deliver A 2 |
509+
| Field or Attribute | Span Publish A | Span Process A 1| Span Process A 2 |
511510
|-|-|-|-|
512-
| Span name | `T publish` | `T deliver` | `T deliver` |
511+
| Span name | `T publish` | `T process` | `T process` |
513512
| Parent | | | |
514513
| Links | | `T publish` | `T publish` |
515514
| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` |
@@ -518,7 +517,7 @@ flowchart LR;
518517
| `server.port` | `1234` | `1234` | `1234` |
519518
| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` |
520519
| `messaging.destination.name` | `"T"` | `"T"` | `"T"` |
521-
| `messaging.operation` | `"publish"` | `"deliver"` | `"deliver"` |
520+
| `messaging.operation` | `"publish"` | `"process"` | `"process"` |
522521
| `messaging.message.id` | `"a"` | `"a"`| `"a"` |
523522

524523
### Batch receiving

‎model/metrics/messaging.yaml

-16
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,6 @@ groups:
2828
unit: "s"
2929
extends: metric.messaging.attributes
3030

31-
- id: metric.messaging.deliver.duration
32-
type: metric
33-
metric_name: messaging.deliver.duration
34-
brief: "Measures the duration of deliver operation."
35-
instrument: histogram
36-
unit: "s"
37-
extends: metric.messaging.attributes
38-
3931
- id: metric.messaging.process.duration
4032
type: metric
4133
metric_name: messaging.process.duration
@@ -61,14 +53,6 @@ groups:
6153
unit: "{message}"
6254
extends: metric.messaging.attributes
6355

64-
- id: metric.messaging.deliver.messages
65-
type: metric
66-
metric_name: messaging.deliver.messages
67-
brief: "Measures the number of delivered messages."
68-
instrument: counter
69-
unit: "{message}"
70-
extends: metric.messaging.attributes
71-
7256
- id: metric.messaging.process.messages
7357
type: metric
7458
metric_name: messaging.process.messages

0 commit comments

Comments
 (0)