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

Clarify producer span relationships and add a messaging example for a batch publishing scenario #509

Merged
merged 11 commits into from
Feb 12, 2024
Merged

Clarify producer span relationships and add a messaging example for a batch publishing scenario #509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
0d42bb3
Add messaging example for batch sending
pyohannes Nov 13, 2023
90eeed2
Add TOC entry
pyohannes Nov 13, 2023
ef464d0
Remove status from examples
pyohannes Nov 15, 2023
9e2377c
WG discussions
pyohannes Dec 1, 2023
ba5c55c
WG discussions
pyohannes Dec 1, 2023
bcd30f6
PR comments
pyohannes Dec 14, 2023
addd64c
Linter error
pyohannes Dec 21, 2023
9ba315b
PR comments
pyohannes Jan 17, 2024
4a37a68
Add description of example diagrams from OTEP 220
pyohannes Jan 17, 2024
b24ba22
Remove obsolete sentence
pyohannes Jan 19, 2024
8e8e83c
Add changelog
pyohannes Feb 9, 2024
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
22 changes: 22 additions & 0 deletions .chloggen/509.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: messaging

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Clarify producer span relationships for messaging semantic conventions

# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [509]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
86 changes: 70 additions & 16 deletions docs/messaging/messaging-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
- [Examples](#examples)
* [Topic with multiple consumers](#topic-with-multiple-consumers)
* [Batch receiving](#batch-receiving)
* [Batch publishing](#batch-publishing)
- [Semantic Conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies)

<!-- tocstop -->
Expand Down Expand Up @@ -203,8 +204,8 @@ The following operations related to messages are defined for these semantic conv

| Operation name | Description |
| -------------- | ----------- |
| `create` | A message is created or passed to a client library for publishing. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. |
| `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. |
| `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. |
| `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. |
| `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. |
| `settle` | One or more messages are settled. |
Expand All @@ -216,8 +217,8 @@ SHOULD be set according to the following table, based on the operation a span de

| Operation name | Span kind|
|----------------|-------------|
| `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. |
| `create` | `PRODUCER` |
| `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. |
pyohannes marked this conversation as resolved.
Show resolved Hide resolved
| `receive` | `CONSUMER` |
| `deliver` | `CONSUMER` |

Expand All @@ -236,20 +237,22 @@ interpret linked traces without the need for additional semantic hints.

#### Producer spans

"Publish" spans SHOULD be created for operations of providing messages for
sending or publishing to an intermediary. A single "Publish" span can account
for a single message, or for multiple messages (in the case of providing
messages in batches). "Create" spans MAY be created. A single "Create" span
SHOULD account only for a single message. "Create" spans SHOULD either be
children or links of the related "Publish" span.
"Create" spans MAY be created when a message is created or passed to the client
library or other component responsible for publishing. A single "Create" span
SHOULD account only for a single message. "Publish" spans SHOULD be created
for operations of sending or publishing a message to an intermediary. A single
"Publish" span can account for a single message, or for multiple messages (in
the case of sending messages in batches).

If a user provides a custom creation context in a message, this context SHOULD
NOT be modified, a "Create" span SHOULD NOT be created, and the "Publish" span
SHOULD link to the custom creation context. Otherwise, if a "Create" span
exists for a message, its context SHOULD be injected into the message. If no
"Create" span exists and no custom creation context is injected into the
message, the context of the related "Publish" span SHOULD be injected into the
message.
NOT be modified and a "Create" span SHOULD NOT be created. Otherwise, if a
"Create" span exists for a message, its context SHOULD be injected into the
message. If no "Create" span exists and no custom creation context is injected
into the message, the context of the related "Publish" span SHOULD be injected
into the message.

The "Publish" span SHOULD always link to the creation context that was injected
into a message either from a "Create" span or as a custom creation context.

#### Consumer spans

Expand Down Expand Up @@ -475,6 +478,14 @@ All attributes that are specific for a messaging system SHOULD be populated in `

## Examples

This section contains a list of examples illustrating the use of the
conventions outlined above. Green boxes denote spans that are required to exist
in order to conform to those conventions. Other boxes denote spans that are not
required and covered by the conventions, but are hopefully helpful in
understanding how messaging spans can be integrated into an overall trace flow.
Solid arrows denote parent/child relationships, dotted arrows denote link
relationships.

### Topic with multiple consumers

Given is a publisher that publishes a message to a topic exchange "T" on RabbitMQ, and two consumers which both get the message delivered.
Expand Down Expand Up @@ -507,7 +518,6 @@ flowchart LR;
| Parent | | | |
| Links | | `T publish` | `T publish` |
| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` |
| Status | `Ok` | `Ok` | `Ok` |
| `server.address` | `"ms"` | `"ms"` | `"ms"` |
| `server.port` | `1234` | `1234` | `1234` |
| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` |
Expand Down Expand Up @@ -546,7 +556,6 @@ flowchart LR;
| Link attributes | | | Span Publish A: `messaging.message.id`: `"a1"` |
| | | | Span Publish B: `messaging.message.id`: `"a2"` |
| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` |
| Status | `Ok` | `Ok` | `Ok` |
| `server.address` | `"ms"` | `"ms"` | `"ms"` |
| `server.port` | `1234` | `1234` | `1234` |
| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` |
Expand All @@ -555,6 +564,51 @@ flowchart LR;
| `messaging.message.id` | `"a1"` | `"a2"` | |
| `messaging.batch.message_count` | | | 2 |

### Batch publishing

Given is a publisher that publishes a batch with two messages to a topic "Q" on
Kafka, and two different consumers receiving one of the messages.

```mermaid
flowchart LR;
subgraph PRODUCER
direction TB
CA[Span Create A]
CB[Span Create B]
P[Span Publish]
end
subgraph CONSUMER1
direction TB
D1[Span Receive A]
end
subgraph CONSUMER2
direction TB
D2[Span Receive B]
end
CA-. link .-P;
CB-. link .-P;
CA-. link .-D1;
CB-. link .-D2;

classDef normal fill:green
class P,CA,CB,D1,D2 normal
linkStyle 0,1,2,3 color:green,stroke:green
```
pyohannes marked this conversation as resolved.
Show resolved Hide resolved

| Field or Attribute | Span Create A | Span Create B | Span Publish | Span Receive A | Span Receive B |
|-|-|-|-|-|-|
| Span name | `Q create` | `Q create` | `Q publish` | `Q receive` | `Q receive` |
| Parent | | | | | |
| Links | | | | Span Create A | Span Create B |
| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | `CONSUMER` | `CONSUMER` |
| `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` |
| `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` |
| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` |
| `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` |
| `messaging.operation` | `"create"` | `"create"` | `"publish"` | `"receive"` | `"receive"` |
| `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` |
| `messaging.batch.message_count` | | | 2 | | |

## Semantic Conventions for specific messaging technologies

More specific Semantic Conventions are defined for the following messaging technologies:
Expand Down
Loading