Merge branch 'main' into messaging-settlement-span

pyohannes · Feb 5, 2024 · 9a6f033 · 9a6f033
2 parents 4c5656a + 482cb01
commit 9a6f033
Show file tree

Hide file tree

Showing 12 changed files with 171 additions and 25 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -37,7 +37,11 @@ release.
 - Add `user_agent.name` and `user_agent.version` attributes
   ([#452](https://github.com/open-telemetry/semantic-conventions/pull/452/))
 - Add an example for gcp_pubsub asynchronous batch publish
-  ([#545](https://github.com/open-telemetry/semantic-conventions/pull/545)).
+  ([#545](https://github.com/open-telemetry/semantic-conventions/pull/545))
+- Add `aws.ecs.task.id` attribute, corrected description for `aws.ecs.task.arn`.
+  ([#597](https://github.com/open-telemetry/semantic-conventions/pull/597))
+- Add Azure Service Bus and Event Hubs messaging attributes
+  ([#572](https://github.com/open-telemetry/semantic-conventions/pull/572))
 - Add messaging semantic conventions for settlement spans
   ([#661](https://github.com/open-telemetry/semantic-conventions/pull/661)).
 

diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
@@ -10,6 +10,8 @@
 - [Kafka Attributes](#kafka-attributes)
 - [RabbitMQ Attributes](#rabbitmq-attributes)
 - [RocketMQ Attributes](#rocketmq-attributes)
+- [Azure Event Hubs Attributes](#azure-event-hubs-attributes)
+- [Azure Service Bus Attributes](#azure-service-bus-attributes)
 
 <!-- tocstop -->
 
@@ -66,9 +68,9 @@ size should be used.
 |---|---|
 | `activemq` | Apache ActiveMQ |
 | `aws_sqs` | Amazon Simple Queue Service (SQS) |
-| `azure_eventgrid` | Azure Event Grid |
-| `azure_eventhubs` | Azure Event Hubs |
-| `azure_servicebus` | Azure Service Bus |
+| `eventgrid` | Azure Event Grid |
+| `eventhubs` | Azure Event Hubs |
+| `servicebus` | Azure Service Bus |
 | `gcp_pubsub` | Google Cloud Pub/Sub |
 | `jms` | Java Message Service |
 | `kafka` | Apache Kafka |
@@ -137,3 +139,23 @@ size should be used.
 | `delay` | Delay message |
 | `transaction` | Transaction message |
 <!-- endsemconv -->
+
+## Azure Event Hubs Attributes
+
+<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-eventhubs) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `messaging.eventhubs.consumer.group` | string | The name of the consumer group the event consumer is associated with. | `indexer` |
+| `messaging.eventhubs.destination.partition.id` | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` |
+| `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` |
+<!-- endsemconv -->
+
+## Azure Service Bus Attributes
+
+<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-servicebus) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `messaging.servicebus.destination.subscription_name` | string | The name of the subscription in the topic messages are received from. | `mySubscription` |
+| `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` |
+| `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` |
+<!-- endsemconv -->
diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md
@@ -40,7 +40,7 @@ document.
 A CloudEvent can be sent directly from producer to consumer.
 For such a scenario, the traditional parent-child trace model works well.
 However, CloudEvents are also used in distributed systems where an event
-can go through many [hops](<https://wikipedia.org/wiki/Hop_(networking)>)
+can go through many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29)
 until it reaches a consumer. In this scenario, the traditional parent-child
 trace model is not sufficient to produce a meaningful trace.
 

diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
@@ -0,0 +1,43 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Google Cloud Pub/Sub
+--->
+
+# Semantic Conventions for Azure Messaging systems
+
+**Status**: [Experimental][DocumentStatus]
+
+The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview) and [Azure Event Hubs](https://learn.microsoft.com/azure/event-hubs/event-hubs-about) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page.
+
+## Azure Service Bus
+
+`messaging.system` MUST be set to `"servicebus"`.
+
+### Span attributes
+
+The following additional attributes are defined:
+<!-- semconv messaging.servicebus -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`messaging.servicebus.destination.subscription_name`](../attributes-registry/messaging.md) | string | The name of the subscription in the topic messages are received from. | `mySubscription` | Conditionally Required: If messages are received from the subscription. |
+| [`messaging.servicebus.message.delivery_count`](../attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | Conditionally Required: [1] |
+| [`messaging.servicebus.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended |
+
+**[1]:** If delivery count is available and is bigger than 0.
+<!-- endsemconv -->
+
+## Azure Event Hubs
+
+`messaging.system` MUST be set to `"eventhubs"`.
+
+### Span attributes
+
+The following additional attributes are defined:
+<!-- semconv messaging.eventhubs -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`messaging.eventhubs.consumer.group`](../attributes-registry/messaging.md) | string | The name of the consumer group the event consumer is associated with. | `indexer` | Conditionally Required: If not default ("$Default"). |
+| [`messaging.eventhubs.destination.partition.id`](../attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` | Conditionally Required: If available. |
+| [`messaging.eventhubs.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended |
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
@@ -81,9 +81,9 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 |---|---|
 | `activemq` | Apache ActiveMQ |
 | `aws_sqs` | Amazon Simple Queue Service (SQS) |
-| `azure_eventgrid` | Azure Event Grid |
-| `azure_eventhubs` | Azure Event Hubs |
-| `azure_servicebus` | Azure Service Bus |
+| `eventgrid` | Azure Event Grid |
+| `eventhubs` | Azure Event Hubs |
+| `servicebus` | Azure Service Bus |
 | `gcp_pubsub` | Google Cloud Pub/Sub |
 | `jms` | Java Message Service |
 | `kafka` | Apache Kafka |

diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
@@ -399,9 +399,9 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 |---|---|
 | `activemq` | Apache ActiveMQ |
 | `aws_sqs` | Amazon Simple Queue Service (SQS) |
-| `azure_eventgrid` | Azure Event Grid |
-| `azure_eventhubs` | Azure Event Hubs |
-| `azure_servicebus` | Azure Service Bus |
+| `eventgrid` | Azure Event Grid |
+| `eventhubs` | Azure Event Hubs |
+| `servicebus` | Azure Service Bus |
 | `gcp_pubsub` | Google Cloud Pub/Sub |
 | `jms` | Java Message Service |
 | `kafka` | Apache Kafka |

diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md
@@ -12,9 +12,10 @@
 | `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended |
 | `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended |
 | `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended |
-| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended |
-| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended |
-| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | Recommended |
+| `aws.ecs.task.arn` | string | The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b`; `arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | Recommended |
+| `aws.ecs.task.family` | string | The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. | `opentelemetry-family` | Recommended |
+| `aws.ecs.task.id` | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | Conditionally Required: If and only if `task.arn` is populated. |
+| `aws.ecs.task.revision` | string | The revision for the task definition used to create the ECS task. | `8`; `26` | Recommended |
 
 `aws.ecs.launchtype` MUST be one of the following:
 

diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
@@ -188,6 +188,8 @@ of `[ 0.01, 0.1, 1, 10 ]`.
 
 ## JVM Threads
 
+**Status**: [Stable][DocumentStatus]
+
 **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.thread.*`
 
 ### Metric: `jvm.thread.count`
@@ -228,6 +230,8 @@ Note that this is the number of platform threads (as opposed to virtual threads)
 
 ## JVM Classes
 
+**Status**: [Stable][DocumentStatus]
+
 **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.class.*`
 
 ### Metric: `jvm.class.loaded`

diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md
@@ -309,7 +309,7 @@ Additional **Recommended** attributes:
 |                                          |                                                                                             |         |                                                   |            | `hw.type` (**Required**)        | `physical_disk`                                 |
 | `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk                                                       | 1       | Gauge                                             | Double     | `state` (**Required**)          | `remaining`                                     |
 | `hw.physical_disk.size`                  | Size of the disk                                                                            | By      | UpDownCounter                                     | Int64      |                                 |                                                 |
-| `hw.physical_disk.smart`                 | Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) attribute | 1       | Gauge                                             | Int        | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc.     |
+| `hw.physical_disk.smart`                 | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1       | Gauge                                             | Int        | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc.     |
 | `hw.status`                              | Operational status: `1` (true) or `0` (false) for each of the possible states               |         | UpDownCounter                                     | Int        | `state` (**Required**)          | `ok`, `degraded`, `failed`, `predicted_failure` |
 |                                          |                                                                                             |         |                                                   |            | `hw.type` (**Required**)        | `physical_disk`                                 |
 

diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml
@@ -248,14 +248,14 @@ groups:
             - id: aws_sqs
               value: 'aws_sqs'
               brief: 'Amazon Simple Queue Service (SQS)'
-            - id: azure_eventgrid
-              value: 'azure_eventgrid'
+            - id: eventgrid
+              value: 'eventgrid'
               brief: 'Azure Event Grid'
-            - id: azure_eventhubs
-              value: 'azure_eventhubs'
+            - id: eventhubs
+              value: 'eventhubs'
               brief: 'Azure Event Hubs'
-            - id: azure_servicebus
-              value: 'azure_servicebus'
+            - id: servicebus
+              value: 'servicebus'
               brief: 'Azure Service Bus'
             - id: gcp_pubsub
               value: 'gcp_pubsub'
@@ -273,3 +273,39 @@ groups:
               value: 'rocketmq'
               brief: 'Apache RocketMQ'
         tag: messaging-generic
+      - id: servicebus.message.delivery_count
+        type: int
+        brief: >
+          Number of deliveries that have been attempted for this message.
+        examples: 2
+        tag: tech-specific-servicebus
+      - id: servicebus.message.enqueued_time
+        type: int
+        brief: >
+          The UTC epoch seconds at which the message has been accepted and stored in the entity.
+        examples: 1701393730
+        tag: tech-specific-servicebus
+      - id: servicebus.destination.subscription_name
+        type: string
+        brief: >
+          The name of the subscription in the topic messages are received from.
+        examples: "mySubscription"
+        tag: tech-specific-servicebus
+      - id: eventhubs.message.enqueued_time
+        type: int
+        brief: >
+          The UTC epoch seconds at which the message has been accepted and stored in the entity.
+        examples: 1701393730
+        tag: tech-specific-eventhubs
+      - id: eventhubs.destination.partition.id
+        type: string
+        brief: >
+          The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it.
+        examples: '1'
+        tag: tech-specific-eventhubs
+      - id: eventhubs.consumer.group
+        type: string
+        brief: >
+          The name of the consumer group the event consumer is associated with.
+        examples: 'indexer'
+        tag: tech-specific-eventhubs
diff --git a/model/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml
@@ -28,15 +28,25 @@ groups:
       - id: task.arn
         type: string
         brief: >
-          The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html).
-        examples: ['arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b']
+          The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids).
+        examples: [
+          'arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b',
+          'arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd'
+        ]
       - id: task.family
         type: string
         brief: >
-          The task definition family this task definition is a member of.
+          The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task.
         examples: ['opentelemetry-family']
+      - id: task.id
+        type: string
+        brief: >
+          The ID of a running ECS task. The ID MUST be extracted from `task.arn`.
+        requirement_level:
+          conditionally_required: If and only if `task.arn` is populated.
+        examples: [ '10838bed-421f-43ef-870a-f43feacbbb5b', '23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' ]
       - id: task.revision
         type: string
         brief: >
-          The revision for this task definition.
+          The revision for the task definition used to create the ECS task.
         examples: ["8", "26"]
diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml
@@ -164,3 +164,29 @@ groups:
         tag: tech-specific-gcp-pubsub
         requirement_level:
           conditionally_required: If the message type has an ordering key set.
+  - id: messaging.servicebus
+    type: attribute_group
+    extends: messaging
+    brief: >
+      Attributes for Azure Service Bus
+    attributes:
+      - ref: messaging.servicebus.message.delivery_count
+        requirement_level:
+          conditionally_required: If delivery count is available and is bigger than 0.
+      - ref: messaging.servicebus.message.enqueued_time
+      - ref: messaging.servicebus.destination.subscription_name
+        requirement_level:
+          conditionally_required: If messages are received from the subscription.
+  - id: messaging.eventhubs
+    type: attribute_group
+    extends: messaging
+    brief: >
+      Attributes for Azure Event Hubs
+    attributes:
+      - ref: messaging.eventhubs.message.enqueued_time
+      - ref: messaging.eventhubs.destination.partition.id
+        requirement_level:
+          conditionally_required: If available.
+      - ref: messaging.eventhubs.consumer.group
+        requirement_level:
+          conditionally_required: If not default ("$Default").