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

Adapt semantic conventions for the span name of messaging systems #690

Merged
merged 18 commits into from
Jul 15, 2020
Merged

Adapt semantic conventions for the span name of messaging systems #690

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
2ab5b8e
Adapt messaging semantic conventions to include the operation in the …
arminru Jul 7, 2020
6554b50
Specify that the operation name must match the respective attribute i…
arminru Jul 7, 2020
57dcf66
Update span names in examples
arminru Jul 7, 2020
30be366
Consolidate definition of operation names into a separate section
arminru Jul 7, 2020
47f053b
Consolidate capitalization
arminru Jul 8, 2020
ca47b6d
Reference Conversation ID definition
arminru Jul 8, 2020
7351144
Consolidate MD syntax
arminru Jul 8, 2020
37ff674
Organize definitions
arminru Jul 8, 2020
beb60a3
Organize definitions
arminru Jul 8, 2020
7bb6131
Reference definitions
arminru Jul 8, 2020
d742494
Allow artificial destinations as span name if neither destination nam…
arminru Jul 10, 2020
d30ffdb
Merge branch 'master' into messaging-span-name
arminru Jul 13, 2020
2b5311d
Do not use conversation IDs for span name
arminru Jul 14, 2020
6d12438
Wording
arminru Jul 14, 2020
1948825
Fix typo
arminru Jul 14, 2020
b274053
Add more links and guidance on messaging.operation
arminru Jul 15, 2020
26610eb
Merge branch 'master' into messaging-span-name
arminru Jul 15, 2020
3fca86f
Fix changelog
arminru Jul 15, 2020
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
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ the release.

## Unreleased

New:

Updates:

- Adapt messaging semantic conventions to include the operation in the span name ([#690](https://github.com/open-telemetry/opentelemetry-specification/pull/690))

## v0.6.0 (07-01-2020)

New:
Expand All @@ -19,6 +25,7 @@ New:
- Add peer.service to provide a user-configured name for a remote service ([#652](https://github.com/open-telemetry/opentelemetry-specification/pull/652))

Updates:

- Improve root Span description ([#645](https://github.com/open-telemetry/opentelemetry-specification/pull/645))
- Extend semantic conventions for RPC and allow non-gRPC calls ([#604](https://github.com/open-telemetry/opentelemetry-specification/pull/604))
- Revise and extend semantic conventions for databases ([#575](https://github.com/open-telemetry/opentelemetry-specification/pull/575))
Expand Down
63 changes: 54 additions & 9 deletions specification/trace/semantic_conventions/messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,16 @@

- [Definitions](#definitions)
- [Conventions](#conventions)
* [Span name](#span-name)
* [Span kind](#span-kind)
* [Operation names](#operation-names)
- [Messaging attributes](#messaging-attributes)
* [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems)
+ [RabbitMQ](#rabbitmq)
- [Examples](#examples)
* [Topic with multiple consumers](#topic-with-multiple-consumers)
* [Batch receiving](#batch-receiving)
* [Batch processing](#batch-processing)

<!-- tocstop -->

Expand All @@ -31,7 +39,9 @@ Often, the waiting for a message is not particularly interesting and hidden away
(in the same way that the listening on a TCP port for an incoming HTTP message is not particularly interesting).
However, in a synchronous conversation, the wait time for a message is important.

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*. The grouping usually happens through some sort of "In-Reply-To:" meta information or an explicit conversation ID. Sometimes a conversation can span multiple message destinations (e.g. initiated via a topic, continued on a temporary one-to-one queue).
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*.
The grouping usually happens through some sort of "In-Reply-To:" meta information or an explicit _conversation ID_ (sometimes called _correlation ID_).
Sometimes a conversation can span multiple message destinations (e.g. initiated via a topic, continued on a temporary one-to-one queue).

Some messaging systems support the concept of *temporary destination* (often only temporary queues) that are established just for a particular set of communication partners (often one to one) or conversation. Often such destinations are unnamed or have an auto-generated name.
arminru marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -41,14 +51,49 @@ Some messaging systems support the concept of *temporary destination* (often onl

Given these definitions, the remainder of this section describes the semantic conventions that shall be followed for Spans describing interactions with messaging systems.

**Span name:** The span name should usually be set to the message destination name.
The conversation ID should be used instead when it is expected to have lower cardinality.
In particular, the conversation ID must be used if the message destination is unnamed or temporary unless multiple conversations can be combined to a logical destination of lower cardinality.
### Span name

**Span kind:** A producer of a message should set the span kind to `PRODUCER` unless it synchronously waits for a response: then it should use `CLIENT`.
The span name SHOULD be set to the message destination name and the operation being performed in the following format:
jmacd marked this conversation as resolved.
Show resolved Hide resolved

```
<destination name> <operation name>
```

The values allowed for `<operation name>` are defined in the section [Operation names](#operation-names) below.

The message destination name, i.e., the name of the topic or queue, is usually a low cardinality identifier suitable to be used as a span name.
If the conversation ID (see [Definitions](#definitions) above) is expected to have lower cardinality than the message destination name, it SHOULD be used instead.
arminru marked this conversation as resolved.
Show resolved Hide resolved
In particular, the conversation ID SHOULD be used if the message destination is unnamed or temporary unless multiple conversations can be combined to a logical destination of lower cardinality.

If the format above is used, the operation name MUST match the `messaging.operation` attribute defined for message consumer spans below.

Examples:

* `shop.orders send`
* `shop.orders receive`
* `shop.orders process`
* `print_jobs send`
* `topic with spaces process`
* `conversation-A1B2C3D4 send`
* `conversation-A1B2C3D4 receive`
* `AuthenticationRequest-Conversations process`

### Span kind

A producer of a message should set the span kind to `PRODUCER` unless it synchronously waits for a response: then it should use `CLIENT`.
The processor of the message should set the kind to `CONSUMER`, unless it always sends back a reply that is directed to the producer of the message
(as opposed to e.g., a queue on which the producer happens to listen): then it should use `SERVER`.

### Operation names

The following operations related to messages are defined for these semantic conventions:

| Operation name | Description |
| -------------- | ----------- |
| `send` | A message is sent to a destination by a message producer/client. |
| `receive` | A message is received from a destination by a message consumer/server. |
| `process` | A message that was previously received from a destination is processed by a message consumer/server. |
arminru marked this conversation as resolved.
Show resolved Hide resolved

## Messaging attributes

| Attribute name | Notes and examples | Required? |
Expand Down Expand Up @@ -77,7 +122,7 @@ For message consumers, the following additional attributes may be set:

| Attribute name | Notes and examples | Required? |
| -------------- | ---------------------------------------------------------------------- | --------- |
| `messaging.operation` | A string identifying which part and kind of message consumption this span describes: either `receive` or `process`. (If the operation is `send`, this attribute must not be set: the operation can be inferred from the span kind in that case.) | No |
| `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 |

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`.
Expand Down Expand Up @@ -108,7 +153,7 @@ Process CB: | Span CB1 |

| Field or Attribute | Span Prod1 | Span CA1 | Span CB1 |
|-|-|-|-|
| Name | `"T"` | `"T"` | `"T"` |
| Span name | `"T send"` | `"T process"` | `"T process"` |
| Parent | | Span Prod1 | Span Prod1 |
| Links | | | |
| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` |
Expand Down Expand Up @@ -137,7 +182,7 @@ Process C: | Span Recv1 |

| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Proc1 | Span Proc2 |
|-|-|-|-|-|-|
| Name | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` |
| Span name | `"Q send"` | `"Q send"` | `"Q receive"` | `"Q process"` | `"Q process"` |
| Parent | | | | Span Recv1 | Span Recv1 |
| Links | | | | Span Prod1 | Span Prod2 |
| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` |
Expand Down Expand Up @@ -170,7 +215,7 @@ Process C: | Span Recv1 | Span Recv2 |

| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Recv2 | Span Proc1 |
|-|-|-|-|-|-|
| Name | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` |
| Span name | `"Q send"` | `"Q send"` | `"Q receive"` | `"Q receive"` | `"Q process"` |
| Parent | | | Span Prod1 | Span Prod2 | |
| Links | | | | | Span Prod1 + Prod2 |
| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` |
Expand Down