diff --git a/.chloggen/509.yaml b/.chloggen/509.yaml new file mode 100644 index 0000000000..620f8e134f --- /dev/null +++ b/.chloggen/509.yaml @@ -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: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 33e7d9ba29..2e39da3b11 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -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) @@ -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. | @@ -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. | | `receive` | `CONSUMER` | | `deliver` | `CONSUMER` | @@ -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 @@ -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. @@ -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"` | @@ -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"` | @@ -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 +``` + +| 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: