docs(messaging): add gcp_pubsub unary pull example (#634)

Co-authored-by: Joao Grassi <[email protected]> Co-authored-by: Joao Grassi <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]>
open-telemetry · Apr 24, 2024 · 387b74f · 387b74f
1 parent 3afe287
commit 387b74f
Show file tree

Hide file tree

Showing 5 changed files with 136 additions and 3 deletions.
diff --git a/.chloggen/634.yaml b/.chloggen/634.yaml
@@ -0,0 +1,25 @@
+# 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: "Add a GCP Pub/Sub unary pull example and the new GCP messaging attributes:
+- `messaging.gcp_pubsub.message.ack_deadline`,
+- `messaging.gcp_pubsub.message.ack_id`,
+- `messaging.gcp_pubsub.message.delivery_attempt`"
+
+# 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: [527]
+
+# (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/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
@@ -87,6 +87,9 @@ size should be used.
 <!-- semconv registry.messaging.gcp_pubsub(omit_requirement_level,full) -->
 | Attribute  | Type | Description  | Examples  | Stability |
 |---|---|---|---|---|
+| `messaging.gcp_pubsub.message.ack_deadline` | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `messaging.gcp_pubsub.message.ack_id` | string | The ack id for a given message. | `ack_id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `messaging.gcp_pubsub.message.delivery_attempt` | int | The delivery attempt for a given message. | `2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 

diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
@@ -14,12 +14,28 @@ The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pub
 
 For Google Cloud Pub/Sub, the following additional attributes are defined:
 
-<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific) -->
+<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific-gcp-pubsub) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`messaging.gcp_pubsub.message.ordering_key`](../attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | `Conditionally Required` If the message type has an ordering key set. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`messaging.gcp_pubsub.message.ack_deadline`](../attributes-registry/messaging.md) | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`messaging.gcp_pubsub.message.ack_id`](../attributes-registry/messaging.md) | string | The ack id for a given message. | `ack_id` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`messaging.gcp_pubsub.message.delivery_attempt`](../attributes-registry/messaging.md) | int | The delivery attempt for a given message. | `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
+## Span names
+
+The span name SHOULD follow the [general messaging span name pattern](../messaging/gcp-pubsub.md): it SHOULD start with the messaging destination name (Topic/Subscription) and contain a low-cardinality name of an operation the span describes:
+
+- Spans for `settle` operations SHOULD follow the `<destination name> ack` or `<destination name> nack` pattern.
+- Spans names for `publish` operations SHOULD follow the `<destination name> send` pattern.
+- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general `<destination name> <operation name>` pattern.
+
+In addition there are the following operations are GCP specific:
+
+- Spans that represents the time from after the message was received to when the message is acknowledged, negatively acknowledged, or expire (used by streaming pull) SHOULD follow the `<destination name> subscribe` pattern.
+- Spans that represent extending the lease for a single message or batch of messages SHOULD follow the`<destination name> modack` pattern.
+
 ## Examples
 
 ### Asynchronous Batch Publish Example
@@ -58,4 +74,64 @@ flowchart LR;
 | `messaging.message.envelope.size` | `1` | `1` | |
 | `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |
 
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md
+### Unary Pull Example
+
+```mermaid
+flowchart TD;
+  subgraph CONSUMER
+  direction LR
+  R1[Receive m1]
+  SM1[Ack m1]
+  EM1[Modack m1]
+  end
+  subgraph PRODUCER
+  direction LR
+  CM1[Create m1]
+  PM1[Publish]
+  end
+  %% Link 0
+  CM1-. link .-PM1;
+  %% Link 1
+  CM1-. link .-R1;
+  %% Link 2
+  R1-. link .-SM1;
+  %% Link 3
+  R1-. link .-EM1;
+
+  %% Style the node and corresponding link
+  %% Producer links and nodes
+  classDef producer fill:green
+  class PM1,CM1 producer
+  linkStyle 0 color:green,stroke:green
+
+  %% Consumer links and nodes
+  classDef consumer fill:#49fcdc
+  class R1 consumer
+  linkStyle 1 color:#49fcdc,stroke:#49fcdc
+
+  classDef ack fill:#577eb5
+  class SM1 ack
+  linkStyle 2 color:#577eb5,stroke:#577eb5
+
+  classDef modack fill:#0560f2
+  class EM1 modack
+  linkStyle 3 color:#0560f2,stroke:#0560f2
+```
+
+| Field or Attribute | Span Create A | Span Publish A | Span Receive A | Span Modack A | Span Ack A |
+|-|-|-|-|-|-|
+| Span name | `T create` | `publish` |  `S receive` | `S modack` |`S ack` |
+| Parent |  |  |  | |  |
+| Links |  | Span Create A | Span Create A | Span Receive A | Span Receive A |
+| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` |`CLIENT` |`CLIENT` |
+| Status | `Ok` | `Ok` | `Ok` |`Ok` | `Ok` |
+| `messaging.destination.name` | `"T"`| `"T"`| `"S"` | `"S"` |`"S"` |
+| `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |  `"gcp_pubsub"` | `"gcp_pubsub"` |
+| `messaging.operation` | `"create"` | `"publish"` | `"receive"` |  `"extend"` |  `"settle"` |
+| `messaging.message.id` | `"a1"` | | `"a1"` | | |
+| `messaging.message.envelope.size` | `1` | `1` | `1`  | | |
+| `messaging.gcp_pubsub.message.ack_id` | | |  | `"ack_id1"` |`"ack_id1"` |
+| `messaging.gcp_pubsub.message.delivery_attempt` | | |  | `0` |  |
+| `messaging.gcp_pubsub.message.ack_deadline` | | |  | | `0` |
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml
@@ -333,6 +333,28 @@ groups:
         brief: >
           The ordering key for a given message. If the attribute is not present, the message does not have an ordering key.
         examples: 'ordering_key'
+        tag: tech-specific-gcp-pubsub
+      - id: gcp_pubsub.message.ack_id
+        type: string
+        stability: experimental
+        brief: >
+         The ack id for a given message.
+        examples: 'ack_id'
+        tag: tech-specific-gcp-pubsub
+      - id: gcp_pubsub.message.ack_deadline
+        type: int
+        stability: experimental
+        brief: >
+          The ack deadline in seconds set for the modify ack deadline request.
+        examples: 10
+        tag: tech-specific-gcp-pubsub
+      - id: gcp_pubsub.message.delivery_attempt
+        type: int
+        stability: experimental
+        brief: >
+          The delivery attempt for a given message.
+        examples: 2
+        tag: tech-specific-gcp-pubsub
   - id: registry.messaging.servicebus
     prefix: messaging
     type: attribute_group

diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml
@@ -188,14 +188,21 @@ groups:
         tag: tech-specific
   - id: messaging.gcp_pubsub
     type: attribute_group
+    stability: experimental
     extends: messaging
     brief: >
       Attributes for Google Cloud Pub/Sub
     attributes:
       - ref: messaging.gcp_pubsub.message.ordering_key
-        tag: tech-specific
+        tag: tech-specific-gcp-pubsub
         requirement_level:
           conditionally_required: If the message type has an ordering key set.
+      - ref: messaging.gcp_pubsub.message.delivery_attempt
+        tag: tech-specific-gcp-pubsub
+      - ref: messaging.gcp_pubsub.message.ack_deadline
+        tag: tech-specific-gcp-pubsub
+      - ref: messaging.gcp_pubsub.message.ack_id
+        tag: tech-specific-gcp-pubsub
   - id: messaging.servicebus
     type: attribute_group
     extends: messaging