Clarify producer span relationships and add a messaging example for a…

… batch publishing scenario (#509)

.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:

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)
 
 <!-- tocstop -->
@@ -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: