docs(messaging): add gcp_pubsub unary pull example

.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 gcp_pubsub unary pull example and gcp_pubsub attributes
+
+# 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: Adds the messaging.gcp_pubsub.message.delivery_attempt,
+  | messaging.gcp_pubsub.message.ack_deadline,
+  | messaging.gcp_pubsub.message.ack_id,
+  | messaging.gcp_pubsub.message.delivery_attempt

docs/attributes-registry/messaging.md

@@ -86,7 +86,7 @@ size should be used.
 <!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-gcp-pubsub) -->
 | Attribute  | Type | Description  | Examples  |
 |---|---|---|---|
-| `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` |
+| `messaging.gcp_pubsub.message.delivery_attempt` | int | The delivery attempt for a given message. | `2` |
 <!-- endsemconv -->
 
 ## Kafka Attributes

docs/messaging/gcp-pubsub.md

@@ -19,6 +19,19 @@ For Google Cloud Pub/Sub, the following additional attributes are defined:
 | [`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. |
 <!-- 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
@@ -50,11 +63,73 @@ flowchart LR;
 | Links |  |  | Span Create A, Span Create B |
 | SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` |
 | Status | `Ok` | `Ok` | `Ok` |
+| `gcp.project_id` | `"P"` | `"P"` | `"P"` |
 | `messaging.batch.message_count` |  |  | 2 |
-| `messaging.destination.name` | `"T"` | `"T"` | `"T"` |
+| `messaging.destination.name` | `"projects/P/topics/T"` | `"projects/P/topics/T"` | `"projects/P/topics/T"` |
 | `messaging.operation` | `"create"` | `"create"` | `"publish"` |
 | `messaging.message.id` | `"a1"` | `"a2"` | |
 | `messaging.message.envelope.size` | `1` | `1` | |
 | `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |
 
+### 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` |
+| `gcp.project_id` | `"P"` | `"P"` | `"P"` |  `"P"` |  `"P"` |
+| `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

model/registry/messaging.yaml

@@ -275,6 +275,21 @@ 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'
+      - id: gcp_pubsub.message.ack_id
+        type: string
+        brief: >
+         The ack id for a given message.
+        examples: 'ack_id'
+      - id: gcp_pubsub.message.ack_deadline
+        type: int
+        brief: >
+          The ack deadline in seconds set for the modify ack deadline request.
+        examples: 10
+      - id: gcp_pubsub.message.delivery_attempt
+        type: int
+        brief: >
+          The delivery attempt for a given message.
+        examples: 2
         tag: tech-specific-gcp-pubsub
       - id: system
         brief: >

model/resource/cloud_provider/gcp/project.yaml

@@ -0,0 +1,12 @@
+groups:
+  - id: gcp.project
+    prefix: gcp.project
+    type: resource
+    brief: >
+      Project related attributes.
+    attributes:
+      - id: gcp.project_id
+        type: string
+        brief: >
+          The name of a GCP Project.
+        examples: ['my-project']

model/trace/messaging.yaml

@@ -189,6 +189,12 @@ groups:
         tag: tech-specific
         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