From 387b74f8a78c56d513063828093ef64341cafffb Mon Sep 17 00:00:00 2001 From: Anna Levenberg Date: Wed, 24 Apr 2024 15:00:50 -0400 Subject: [PATCH] docs(messaging): add gcp_pubsub unary pull example (#634) Co-authored-by: Joao Grassi Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Liudmila Molkova --- .chloggen/634.yaml | 25 +++++++++ docs/attributes-registry/messaging.md | 3 + docs/messaging/gcp-pubsub.md | 80 ++++++++++++++++++++++++++- model/registry/messaging.yaml | 22 ++++++++ model/trace/messaging.yaml | 9 ++- 5 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 .chloggen/634.yaml diff --git a/.chloggen/634.yaml b/.chloggen/634.yaml new file mode 100644 index 000000000..16b837ff8 --- /dev/null +++ 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 index b41d34016..25bad90a5 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -87,6 +87,9 @@ size should be used. | 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) | diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index b586668d6..3ed71fdcf 100644 --- 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: - + | 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) | +## 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 ` ack` or ` nack` pattern. +- Spans names for `publish` operations SHOULD follow the ` send` pattern. +- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` 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 ` subscribe` pattern. +- Spans that represent extending the lease for a single message or batch of messages SHOULD follow the` 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 index 4a2c6a271..f22f58f15 100644 --- 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 index f12a96b1d..542edec12 100644 --- 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