From e37eac79943586b6b4e18c8e0bb2d061d4850cb4 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 12 Jan 2024 14:01:13 -0300 Subject: [PATCH 1/9] Revert "Clarify that service.* conventions apply to all telemetry sources" (#638) --- CHANGELOG.md | 3 --- docs/resource/README.md | 4 ++-- model/resource/service.yaml | 7 +------ model/resource/service_experimental.yaml | 2 +- 4 files changed, 4 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dfe18a4a3..6f597bc797 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,9 +23,6 @@ release. ### Fixes -- Clarify that `service.*` attributes apply to all telemetry sources. - ([#630](https://github.com/open-telemetry/semantic-conventions/pull/630)) - ## v1.24.0 (2023-12-15) ### Breaking diff --git a/docs/resource/README.md b/docs/resource/README.md index 1c0b63718f..a77cbd2f69 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -77,7 +77,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet **type:** `service` -**Description:** A telemetry source. OpenTelemetry has adopted a broad interpretation such that every telemetry source is a service. Examples include, but are not limited to: web services, hosts, mobile applications, browser application, edge computing devices, functions as a service, databases, message brokers, etc. Specific types of telemetry sources may have additional conventions defining domain specific information, but the `service` conventions are applicable to all telemetry sources. +**Description:** A service instance. | Attribute | Type | Description | Examples | Requirement Level | @@ -94,7 +94,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet **type:** `service` -**Description:** Experimental additions to service. +**Description:** Additions to service instance. | Attribute | Type | Description | Examples | Requirement Level | diff --git a/model/resource/service.yaml b/model/resource/service.yaml index fc3d3a6c52..05b2e02698 100644 --- a/model/resource/service.yaml +++ b/model/resource/service.yaml @@ -3,12 +3,7 @@ groups: prefix: service type: resource brief: > - A telemetry source. OpenTelemetry has adopted a broad interpretation such that every - telemetry source is a service. Examples include, but are not limited to: web services, - hosts, mobile applications, browser application, edge computing devices, functions as - a service, databases, message brokers, etc. Specific types of telemetry sources may have - additional conventions defining domain specific information, but the `service` - conventions are applicable to all telemetry sources. + A service instance. attributes: - id: name type: string diff --git a/model/resource/service_experimental.yaml b/model/resource/service_experimental.yaml index 9103ac7531..43c869ee35 100644 --- a/model/resource/service_experimental.yaml +++ b/model/resource/service_experimental.yaml @@ -3,7 +3,7 @@ groups: prefix: service type: resource brief: > - Experimental additions to service. + A service instance. attributes: - id: namespace type: string From 50e2eac498cf7b0e9d07148594350c67934550be Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 17 Jan 2024 17:25:10 +0100 Subject: [PATCH 2/9] Move messaging attributes in registry to system-specific sections (#643) --- docs/attributes-registry/messaging.md | 120 +++++++++++++++++--------- model/registry/messaging.yaml | 30 +++++++ 2 files changed, 109 insertions(+), 41 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 626d8cc59f..c874710646 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -3,9 +3,19 @@ # Messaging -## Messaging Attributes + - +- [Generic Messaging Attributes](#generic-messaging-attributes) +- [GCP Pub/Sub Attributes](#gcp-pubsub-attributes) +- [Kafka Attributes](#kafka-attributes) +- [RabbitMQ Attributes](#rabbitmq-attributes) +- [RocketMQ Attributes](#rocketmq-attributes) + + + +## Generic Messaging Attributes + + | Attribute | Type | Description | Examples | |---|---|---|---| | `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | @@ -16,27 +26,11 @@ | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | | `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | | `messaging.destination_publish.name` | string | The name of the original destination the message was published to [4] | `MyQueue`; `MyTopic` | -| `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.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | -| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [5] | `myKey` | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | -| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | -| `messaging.message.body.size` | int | The size of the message body in bytes. [6] | `1439` | +| `messaging.message.body.size` | int | The size of the message body in bytes. [5] | `1439` | | `messaging.message.conversation_id` | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [7] | `2738` | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [6] | `2738` | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | -| `messaging.operation` | string | A string identifying the kind of messaging operation. [8] | `publish` | -| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | -| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | -| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | -| `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | -| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | +| `messaging.operation` | string | A string identifying the kind of messaging operation. [7] | `publish` | | `messaging.system` | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | **[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. @@ -49,15 +43,13 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[4]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. -**[5]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. - -**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[5]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[6]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[8]:** If a custom value is used, it MUST be of low cardinality. +**[7]:** If a custom value is used, it MUST be of low cardinality. `messaging.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -68,6 +60,67 @@ size should be used. | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | | `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | +`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `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 | +| `gcp_pubsub` | Google Cloud Pub/Sub | +| `jms` | Java Message Service | +| `kafka` | Apache Kafka | +| `rabbitmq` | RabbitMQ | +| `rocketmq` | Apache RocketMQ | + + +## GCP Pub/Sub Attributes + + +| 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` | + + +## Kafka Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | +| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | +| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | +| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | +| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | + +**[1]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. + + +## RabbitMQ Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | + + +## RocketMQ Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | +| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | +| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | +| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | +| `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | +| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | +| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | +| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | +| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | + `messaging.rocketmq.consumption_model` MUST be one of the following: | Value | Description | @@ -83,19 +136,4 @@ size should be used. | `fifo` | FIFO message | | `delay` | Delay message | | `transaction` | Transaction message | - -`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `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 | -| `gcp_pubsub` | Google Cloud Pub/Sub | -| `jms` | Java Message Service | -| `kafka` | Apache Kafka | -| `rabbitmq` | RabbitMQ | -| `rocketmq` | Apache RocketMQ | diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index c7ba8fd457..6f638976a3 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -12,11 +12,13 @@ groups: When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. examples: [0, 1, 2] + tag: messaging-generic - id: client_id type: string brief: > A unique identifier for the client that consumes or produces a message. examples: ['client-5', 'myhost@8742@s8083jm'] + tag: messaging-generic - id: destination.name type: string brief: 'The message destination name' @@ -24,6 +26,7 @@ groups: Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] + tag: messaging-generic - id: destination.template type: string brief: Low cardinality representation of the messaging destination name @@ -34,15 +37,19 @@ groups: the underlying template is of low cardinality and can be effectively used for grouping and aggregation. examples: ['/customers/{customerId}'] + tag: messaging-generic - id: destination.anonymous type: boolean brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + tag: messaging-generic - id: destination.temporary type: boolean brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' + tag: messaging-generic - id: destination_publish.anonymous type: boolean brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + tag: messaging-generic - id: destination_publish.name type: string brief: 'The name of the original destination the message was published to' @@ -50,17 +57,20 @@ groups: The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] + tag: messaging-generic - id: kafka.consumer.group type: string brief: > Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. examples: 'my-group' + tag: tech-specific-kafka - id: kafka.destination.partition type: int brief: > Partition the message is sent to. examples: 2 + tag: tech-specific-kafka - id: kafka.message.key type: string brief: > @@ -71,20 +81,24 @@ groups: If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. examples: 'myKey' + tag: tech-specific-kafka - id: kafka.message.offset type: int brief: > The offset of a record in the corresponding Kafka partition. examples: 42 + tag: tech-specific-kafka - id: kafka.message.tombstone type: boolean brief: 'A boolean that is true if the message is a tombstone.' + tag: tech-specific-kafka - id: message.conversation_id type: string brief: > The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". examples: 'MyConversationId' + tag: messaging-generic - id: message.envelope.size type: int brief: > @@ -93,10 +107,12 @@ groups: This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. examples: 2738 + tag: messaging-generic - id: message.id type: string brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' examples: '452a7c7c7c7048c2f887f61572b18fc2' + tag: messaging-generic - id: message.body.size type: int brief: > @@ -105,6 +121,7 @@ groups: This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. examples: 1439 + tag: messaging-generic - id: operation type: allow_custom_values: true @@ -132,16 +149,19 @@ groups: brief: > A string identifying the kind of messaging operation. note: If a custom value is used, it MUST be of low cardinality. + tag: messaging-generic - id: rabbitmq.destination.routing_key type: string brief: > RabbitMQ message routing key. examples: 'myKey' + tag: tech-specific-rabbitmq - id: rocketmq.client_group type: string brief: > Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. examples: 'myConsumerGroup' + tag: tech-specific-rocketmq - id: rocketmq.consumption_model type: allow_custom_values: false @@ -154,31 +174,37 @@ groups: brief: 'Broadcasting consumption model' brief: > Model of message consumption. This only applies to consumer spans. + tag: tech-specific-rocketmq - id: rocketmq.message.delay_time_level type: int brief: > The delay time level for delay message, which determines the message delay time. examples: 3 + tag: tech-specific-rocketmq - id: rocketmq.message.delivery_timestamp type: int brief: > The timestamp in milliseconds that the delay message is expected to be delivered to consumer. examples: 1665987217045 + tag: tech-specific-rocketmq - id: rocketmq.message.group type: string brief: > It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. examples: 'myMessageGroup' + tag: tech-specific-rocketmq - id: rocketmq.message.keys type: string[] brief: > Key(s) of message, another way to mark message besides message id. examples: ['keyA', 'keyB'] + tag: tech-specific-rocketmq - id: rocketmq.message.tag type: string brief: > The secondary classifier of message besides topic. examples: tagA + tag: tech-specific-rocketmq - id: rocketmq.message.type type: allow_custom_values: false @@ -197,16 +223,19 @@ groups: brief: 'Transaction message' brief: > Type of message. + tag: tech-specific-rocketmq - id: rocketmq.namespace type: string brief: > Namespace of RocketMQ resources, resources in different namespaces are individual. examples: 'myNamespace' + tag: tech-specific-rocketmq - id: gcp_pubsub.message.ordering_key type: string 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: system brief: > An identifier for the messaging system being used. See below for a list of well-known identifiers. @@ -243,3 +272,4 @@ groups: - id: rocketmq value: 'rocketmq' brief: 'Apache RocketMQ' + tag: messaging-generic From bb017fa80a23b25a05a02cc49b0dc715f9653a2e Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 17 Jan 2024 17:52:22 +0100 Subject: [PATCH 3/9] Remove obsolete footnotes for messaging attributes (#642) Co-authored-by: Joao Grassi --- docs/messaging/messaging-spans.md | 73 ++++++++++++++----------------- model/trace/messaging.yaml | 8 ---- 2 files changed, 32 insertions(+), 49 deletions(-) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 7562e2972b..b80eec3a84 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -24,7 +24,6 @@ + [Producer spans](#producer-spans) + [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - * [Attribute namespaces](#attribute-namespaces) * [Consumer attributes](#consumer-attributes) * [Per-message attributes](#per-message-attributes) * [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) @@ -272,6 +271,19 @@ messages were received). For each message it accounts for, the "Deliver" or ## Messaging attributes +Messaging attributes are organized into the following namespaces: + +- `messaging.message`: Contains [per-message attributes](#per-message-attributes) that describe individual messages. Those attributes are relevant only for spans or links that represent a single message. +- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details. +- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details. +- `messaging.batch`: Contains attributes that describe batch operations. +- `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details. + +The communication with the intermediary is described with general [network attributes]. + +Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace +as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| @@ -282,20 +294,20 @@ messages were received). For each message it accounts for, the "Deliver" or | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] | | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | Conditionally Required: [9] | | [`messaging.destination.temporary`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [10] | -| [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | Recommended: [12] | -| [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [13] | -| [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [14] | `2738` | Recommended: [15] | -| [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [16] | -| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [17] | `publish` | Required | +| [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | Recommended | +| [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended | +| [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended | +| [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended | +| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [13] | `publish` | Required | | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [18] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [19] | `3.1.1` | Recommended | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [20] | `tcp`; `udp` | Recommended | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [21] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [22] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [23] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [15] | `3.1.1` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [16] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [17] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [19] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -335,34 +347,26 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[12]:** Only if span represents operation on a single message. - -**[13]:** Only if span represents operation on a single message. - -**[14]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[12]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[15]:** Only if span represents operation on a single message. +**[13]:** If a custom value is used, it MUST be of low cardinality. -**[16]:** Only for spans that represent an operation on a single message. +**[14]:** The value SHOULD be normalized to lowercase. -**[17]:** If a custom value is used, it MUST be of low cardinality. +**[15]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[18]:** The value SHOULD be normalized to lowercase. - -**[19]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[20]:** The value SHOULD be normalized to lowercase. +**[16]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[21]:** The value SHOULD be normalized to lowercase. +**[17]:** The value SHOULD be normalized to lowercase. -**[22]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[18]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[23]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[19]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -415,19 +419,6 @@ Additionally `server.port` from the [network attributes][] is recommended. Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). These attributes should be set to the broker to which the message is sent/from which it is received. -### Attribute namespaces - -- `messaging.message`: Contains attributes that describe individual messages -- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details -- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details -- `messaging.batch`: Contains attributes that describe batch operations -- `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details - -Communication with broker is described with general [network attributes]. - -Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace -as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). - [network attributes]: /docs/general/attributes.md#server-and-client-attributes [`network.transport`]: /docs/general/attributes.md#network-attributes [Hangfire]: https://www.hangfire.io/ diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index be7a4441c7..011ad09570 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -77,17 +77,9 @@ groups: requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - ref: messaging.message.id - requirement_level: - recommended: Only for spans that represent an operation on a single message. - ref: messaging.message.conversation_id - requirement_level: - recommended: Only if span represents operation on a single message. - ref: messaging.message.envelope.size - requirement_level: - recommended: Only if span represents operation on a single message. - ref: messaging.message.body.size - requirement_level: - recommended: Only if span represents operation on a single message. - ref: server.address - ref: network.peer.address tag: connection-level From a41f0e8961860205f37e585443d4de3d12d25c2a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 19 Jan 2024 05:28:12 -0500 Subject: [PATCH 4/9] [editorial] Fix/adjust link to use https rather than http (#645) --- docs/database/couchdb.md | 2 +- model/trace/database.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 6702a92b40..8025aacd08 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -19,7 +19,7 @@ described on this page. |---|---|---|---|---| | [`db.operation`](../attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | Conditionally Required: If `db.statement` is not applicable. | -**[1]:** In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). +**[1]:** In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 9df75ee20f..a896527ac7 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -116,7 +116,7 @@ groups: the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): - [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). + [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). - id: db.redis type: span From d21135e07ce9ca1ba05581021aebe84cc1d27ee8 Mon Sep 17 00:00:00 2001 From: Braydon Kains <93549768+braydonk@users.noreply.github.com> Date: Tue, 23 Jan 2024 03:37:27 -0500 Subject: [PATCH 5/9] Generate process metrics with `semconv` yaml (#330) Co-authored-by: Joao Grassi --- .yamllint | 3 + CHANGELOG.md | 14 ++ docs/system/process-metrics.md | 220 ++++++++++++++++++++++++++--- model/metrics/process-metrics.yaml | 120 ++++++++++++++++ schema-next.yaml | 31 ++++ 5 files changed, 368 insertions(+), 20 deletions(-) create mode 100644 model/metrics/process-metrics.yaml diff --git a/.yamllint b/.yamllint index 39c91cefa1..70b17e868b 100644 --- a/.yamllint +++ b/.yamllint @@ -1,5 +1,8 @@ extends: default +ignore-from-file: + - .gitignore + rules: document-start: disable octal-values: enable diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f597bc797..16ab5dcee3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,20 @@ release. ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) - Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources ([#625](https://github.com/open-telemetry/semantic-conventions/pull/625)) +- BREAKING: Generate process metrics from YAML + ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) + - Rename `process.threads` to `process.thread.count` + - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` + - Rename attributes for `process.cpu.*` + - `state` to `process.cpu.state` + - Change attributes for `process.disk.io` + - Instead of `direction` use `disk.io.direction` from global registry + - Change attributes for `process.network.io` + - Instead of `direction` use `network.io.direction` from global registry + - Rename attributes for `process.context_switches` + - `type` to `process.context_switch_type` + - Rename attributes for `process.paging.faults` + - `type` to `process.paging.fault_type` ### Features diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index c619763717..35e343349e 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -19,9 +19,17 @@ metrics](/docs/runtime/README.md#metrics). -- [Metric Instruments](#metric-instruments) - * [Process](#process) -- [Attributes](#attributes) +- [Process Metrics](#process-metrics) + * [Metric: `process.cpu.time`](#metric-processcputime) + * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + * [Metric: `process.memory.usage`](#metric-processmemoryusage) + * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + * [Metric: `process.disk.io`](#metric-processdiskio) + * [Metric: `process.network.io`](#metric-processnetworkio) + * [Metric: `process.thread.count`](#metric-processthreadcount) + * [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + * [Metric: `process.context_switches`](#metric-processcontext_switches) + * [Metric: `process.paging.faults`](#metric-processpagingfaults) @@ -35,27 +43,199 @@ metrics](/docs/runtime/README.md#metrics). > * SHOULD introduce a control mechanism to allow users to opt-in to the new > conventions once the migration plan is finalized. -## Metric Instruments +## Process Metrics -### Process +### Metric: `process.cpu.time` -Below is a table of Process metric instruments. +This metric is [recommended][MetricRecommended]. -| Name | Instrument Type ([\*](/docs/general/metrics.md#instrument-types)) | Unit | Description | Labels | -|---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.memory.usage` | UpDownCounter | By | The amount of physical memory in use. | | -| `process.memory.virtual` | UpDownCounter | By | The amount of committed virtual memory. | | -| `process.disk.io` | Counter | By | Disk bytes transferred. | `direction` SHOULD be one of: `read`, `write` | -| `process.network.io` | Counter | By | Network bytes transferred. | `direction` SHOULD be one of: `receive`, `transmit` | -| `process.threads` | UpDownCounter | {thread} | Process threads count. | | -| `process.open_file_descriptors` | UpDownCounter | {count} | Number of file descriptors in use by the process. | | -| `process.context_switches` | Counter | {count} | Number of times the process has been context switched. | `type` SHOULD be one of: `involuntary`, `voluntary` | -| `process.paging.faults` | Counter | {fault} | Number of page faults the process has made. | `type`, if specified, SHOULD be one of: `major` (for major, or hard, page faults), `minor` (for minor, or soft, page faults). | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | + -## Attributes + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | -Process metrics SHOULD be associated with a [`process`](/docs/resource/process.md#process) resource whose attributes provide additional context about the process. +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | + + +### Metric: `process.cpu.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | + +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | + + +### Metric: `process.memory.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | + + + + + +### Metric: `process.memory.virtual` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | + + + + + +### Metric: `process.disk.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.disk.io` | Counter | `By` | Disk bytes transferred. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | + +`disk.io.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `process.network.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.network.io` | Counter | `By` | Network bytes transferred. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | + +`network.io.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + + +### Metric: `process.thread.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.thread.count` | UpDownCounter | `{thread}` | Process threads count. | + + + + + +### Metric: `process.open_file_descriptor.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.open_file_descriptor.count` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | + + + + + +### Metric: `process.context_switches` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.context_switch_type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | + +`process.context_switch_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `voluntary` | voluntary | +| `involuntary` | involuntary | + + +### Metric: `process.paging.faults` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.paging.fault_type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | + +`process.paging.fault_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `major` | major | +| `minor` | minor | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml new file mode 100644 index 0000000000..cc663a9eaf --- /dev/null +++ b/model/metrics/process-metrics.yaml @@ -0,0 +1,120 @@ +groups: + - id: attributes.process.cpu + prefix: process.cpu + type: attribute_group + brief: "Attributes for process CPU metrics." + attributes: + - id: state + brief: "The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels." + type: + allow_custom_values: true + members: + - id: system + value: 'system' + - id: user + value: 'user' + - id: wait + value: 'wait' + + - id: metric.process.cpu.time + type: metric + metric_name: process.cpu.time + brief: "Total CPU seconds broken down by different states." + instrument: counter + unit: "s" + attributes: + - ref: process.cpu.state + + - id: metric.process.cpu.utilization + type: metric + metric_name: process.cpu.utilization + brief: "Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process." + instrument: gauge + unit: "1" + attributes: + - ref: process.cpu.state + + - id: metric.process.memory.usage + type: metric + metric_name: process.memory.usage + brief: "The amount of physical memory in use." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.memory.virtual + type: metric + metric_name: process.memory.virtual + brief: "The amount of committed virtual memory." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.disk.io + type: metric + metric_name: process.disk.io + prefix: process.disk + brief: "Disk bytes transferred." + instrument: counter + unit: "By" + attributes: + - ref: disk.io.direction + + - id: metric.process.network.io + type: metric + metric_name: process.network.io + brief: "Network bytes transferred." + instrument: counter + unit: "By" + attributes: + - ref: network.io.direction + + - id: metric.process.thread.count + type: metric + metric_name: process.thread.count + brief: "Process threads count." + instrument: updowncounter + unit: "{thread}" + attributes: [] + + - id: metric.process.open_file_descriptor.count + type: metric + metric_name: process.open_file_descriptor.count + brief: "Number of file descriptors in use by the process." + instrument: updowncounter + unit: "{count}" + attributes: [] + + - id: metric.process.context_switches + type: metric + metric_name: process.context_switches + brief: "Number of times the process has been context switched." + instrument: counter + unit: "{count}" + attributes: + - id: process.context_switch_type + brief: "Specifies whether the context switches for this data point were voluntary or involuntary." + type: + allow_custom_values: true + members: + - id: voluntary + value: 'voluntary' + - id: involuntary + value: 'involuntary' + + - id: metric.process.paging.faults + type: metric + metric_name: process.paging.faults + brief: "Number of page faults the process has made." + instrument: counter + unit: "{fault}" + attributes: + - id: process.paging.fault_type + brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." + type: + allow_custom_values: true + members: + - id: major + value: 'major' + - id: minor + value: 'minor' diff --git a/schema-next.yaml b/schema-next.yaml index 58de42a543..23ebad9a35 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -18,6 +18,37 @@ versions: attribute_map: container.labels: container.label k8s.pod.labels: k8s.pod.label + # https://github.com/open-telemetry/semantic-conventions/pull/330 + - rename_metrics: + process.threads: process.thread.count + process.open_file_descriptors: process.open_file_descriptor.count + - rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization + - rename_attributes: + attribute_map: + direction: disk.io.direction + apply_to_metrics: + - process.disk.io + - rename_attributes: + attribute_map: + type: process.context_switch_type + apply_to_metrics: + - process.context_switches + - rename_attributes: + attribute_map: + direction: network.io.direction + apply_to_metrics: + - process.network.io + - rename_attributes: + attribute_map: + type: process.paging.fault_type + apply_to_metrics: + - process.paging.faults + 1.24.0: metrics: changes: From c3e35ee7c72322a78220b739fcec6eae0dcc3622 Mon Sep 17 00:00:00 2001 From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com> Date: Wed, 24 Jan 2024 14:51:56 +0100 Subject: [PATCH 6/9] added remaining ECS fields to the useragent (#452) Co-authored-by: Trask Stalnaker --- CHANGELOG.md | 4 +++- docs/attributes-registry/user-agent.md | 6 ++++++ model/registry/user-agent.yaml | 14 ++++++++++++++ 3 files changed, 23 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 16ab5dcee3..bd719ed32b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,8 +32,10 @@ release. - Add `azure_container_apps` to `cloud.platform` semantic conventions ([#615](https://github.com/open-telemetry/semantic-conventions/pull/615)) +- 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)) ### Fixes diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 589f722f87..f75c5d22ce 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -8,5 +8,11 @@ | Attribute | Type | Description | Examples | |---|---|---|---| +| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name [1] | `Safari` | | `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | +| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2` | + +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string + +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 0fbc5c9f2a..29e00ff6bc 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -11,3 +11,17 @@ groups: Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. examples: ['CERN-LineMode/2.15 libwww/2.17b3', 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + - id: name + type: string + brief: > + Name of the user-agent extracted from original. Usually refers to the browser's name + examples: ['Safari'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's name from original string + - id: version + type: string + brief: > + Version of the user-agent extracted from original. Usually refers to the browser's version + examples: ['14.1.2'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's version from original string From dd41eac32f6bb391f49bd7e4deab5356b1a5505e Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 24 Jan 2024 15:57:19 +0100 Subject: [PATCH 7/9] Make `network.protocol.name` conditionally required for messaging (#644) Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/messaging/messaging-metrics.md | 16 +++++++++------- docs/messaging/messaging-spans.md | 24 +++++++++++++----------- model/messaging-common.yaml | 2 ++ 4 files changed, 26 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd719ed32b..86d2bb5ec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) - Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources ([#625](https://github.com/open-telemetry/semantic-conventions/pull/625)) +- Make `network.protocol.name` conditionally required for messaging + ([#644](https://github.com/open-telemetry/semantic-conventions/pull/644)) - BREAKING: Generate process metrics from YAML ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - Rename `process.threads` to `process.thread.count` diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index b2f7046bdd..d2fbda03dc 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -29,10 +29,10 @@ All messaging metrics share the same set of attributes: | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] | | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. | | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | -| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `3.1.1` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Conditionally Required: [7] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [8] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -61,11 +61,13 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[6]:** The value SHOULD be normalized to lowercase. -**[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[7]:** Only for messaging systems and frameworks that support more than one protocol. -**[8]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[8]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index b80eec3a84..f6d647a9bf 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -302,12 +302,12 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [15] | `3.1.1` | Recommended | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [16] | `tcp`; `udp` | Recommended | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [17] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [19] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Conditionally Required: [15] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [16] | `3.1.1` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [18] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [19] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [20] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -354,19 +354,21 @@ size should be used. **[14]:** The value SHOULD be normalized to lowercase. -**[15]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[15]:** Only for messaging systems and frameworks that support more than one protocol. -**[16]:** The value SHOULD be normalized to lowercase. +**[16]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[17]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[17]:** The value SHOULD be normalized to lowercase. +**[18]:** The value SHOULD be normalized to lowercase. -**[18]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[19]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[19]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[20]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml index 07ef5f4a78..92bddd7924 100644 --- a/model/messaging-common.yaml +++ b/model/messaging-common.yaml @@ -18,6 +18,8 @@ groups: - ref: server.port - ref: network.protocol.name examples: ['amqp', 'mqtt'] + requirement_level: + conditionally_required: Only for messaging systems and frameworks that support more than one protocol. tag: connection-level - ref: network.protocol.version tag: connection-level From 3f30d418f86af82a908a8437bd8b03a42d5adf79 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 24 Jan 2024 19:57:37 +0100 Subject: [PATCH 8/9] Add stale bot workflow (#668) --- .github/workflows/stale-pr.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .github/workflows/stale-pr.yml diff --git a/.github/workflows/stale-pr.yml b/.github/workflows/stale-pr.yml new file mode 100644 index 0000000000..e463791fa9 --- /dev/null +++ b/.github/workflows/stale-pr.yml @@ -0,0 +1,17 @@ +name: "Close stale spull requests" +on: + schedule: + - cron: "12 3 * * *" # arbitrary time not to DDOS GitHub + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + stale-pr-message: 'This PR was marked stale due to lack of activity. It will be closed in 7 days.' + close-pr-message: 'Closed as inactive. Feel free to reopen if this PR is still being worked on.' + exempt-pr-labels: 'release:after-ga' + days-before-stale: 15 + days-before-close: 7 From fa0725719bcfbab57fa17961faef5f9448d20828 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 25 Jan 2024 07:27:35 -0800 Subject: [PATCH 9/9] (editorial) Update http.resend_count references to http.request.resend_count (#666) Co-authored-by: Joao Grassi --- docs/http/http-spans.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 1193cf2cb0..9ed7173c1b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -277,7 +277,7 @@ Retries and redirects cause more than one physical HTTP request to be sent. A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. -Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. +Each time an HTTP request is resent, the `http.request.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. See the examples for more details about: @@ -433,11 +433,11 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET / - 500 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET / - 500 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | | | --- server (SERVER, trace=t1, span=s5) | - -- GET / - 200 (CLIENT, trace=t1, span=s6, http.resend_count=2) + -- GET / - 200 (CLIENT, trace=t1, span=s6, http.request.resend_count=2) | --- server (SERVER, trace=t1, span=s7) ``` @@ -449,11 +449,11 @@ GET / - 500 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET / - 500 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET / - 500 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) -GET / - 200 (CLIENT, trace=t3, span=s1, http.resend_count=2) +GET / - 200 (CLIENT, trace=t3, span=s1, http.request.resend_count=2) | --- server (SERVER, trace=t3, span=s1) ``` @@ -469,7 +469,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -481,7 +481,7 @@ GET /hello - 401 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ``` @@ -497,7 +497,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -509,7 +509,7 @@ GET / - 302 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ```