From 3beb6cd937229329fd9bbf573a9f8c375be0b535 Mon Sep 17 00:00:00 2001 From: Marcin Kielar Date: Tue, 30 Jan 2024 11:50:38 +0100 Subject: [PATCH 1/4] Improvements for AWS/ECS attributes (#597) Co-authored-by: Pablo Baeyens Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/resource/cloud-provider/aws/ecs.md | 7 ++++--- model/resource/cloud_provider/aws/ecs.yaml | 18 ++++++++++++++---- 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86d2bb5ec2..7b6146e03f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,8 @@ release. ([#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)) +- Add `aws.ecs.task.id` attribute, corrected description for `aws.ecs.task.arn`. + ([#597](https://github.com/open-telemetry/semantic-conventions/pull/597)) ### Fixes diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index 362b66dde9..2edafe56b9 100644 --- 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/model/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml index 2c6b8c9ba5..a40f950c18 100644 --- 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"] From 4266051473ab56209104ff4106961665c4fe86e9 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 31 Jan 2024 10:55:34 -0500 Subject: [PATCH 2/4] [editorial] Use canonical wikipedia links (#678) --- docs/cloudevents/cloudevents-spans.md | 2 +- docs/system/hardware-metrics.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 4064262d1d..1236b745ad 100644 --- 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]() +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/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 09ba773b65..a5c9f8ac01 100644 --- 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` | From 13a8238b4dcdd4261751b16012edef6388654f86 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 1 Feb 2024 08:40:35 -0800 Subject: [PATCH 3/4] Define additional Azure messaging attributes (#572) --- CHANGELOG.md | 2 ++ docs/attributes-registry/messaging.md | 28 ++++++++++++++-- docs/messaging/azure-messaging.md | 43 ++++++++++++++++++++++++ docs/messaging/messaging-metrics.md | 6 ++-- docs/messaging/messaging-spans.md | 6 ++-- model/registry/messaging.yaml | 48 +++++++++++++++++++++++---- model/trace/messaging.yaml | 26 +++++++++++++++ 7 files changed, 144 insertions(+), 15 deletions(-) create mode 100644 docs/messaging/azure-messaging.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b6146e03f..ed085131b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ release. ([#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)) ### Fixes diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index c874710646..2ec5ad6c2d 100644 --- 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) @@ -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 | + +## Azure Event Hubs Attributes + + +| 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` | + + +## Azure Service Bus Attributes + + +| 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` | + diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md new file mode 100644 index 0000000000..35e17ec2c3 --- /dev/null +++ b/docs/messaging/azure-messaging.md @@ -0,0 +1,43 @@ + + +# 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: + +| 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. + + +## Azure Event Hubs + +`messaging.system` MUST be set to `"eventhubs"`. + +### Span attributes + +The following additional attributes are defined: + +| 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 | + + +[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 index d2fbda03dc..dc9d1ef9b0 100644 --- 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 index f6d647a9bf..19db054994 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -391,9 +391,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/model/registry/messaging.yaml b/model/registry/messaging.yaml index 6f638976a3..868df05065 100644 --- 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/trace/messaging.yaml b/model/trace/messaging.yaml index 011ad09570..cc980de321 100644 --- 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"). From 482cb01c4598429c65dd0b123b30259f41b360cb Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 2 Feb 2024 05:03:14 -0800 Subject: [PATCH 4/4] [Editorial] Add missing stable status markers (#682) --- docs/runtime/jvm-metrics.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 7c913815e2..780c15afd3 100644 --- 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`