From cafda7127683b7f667e27cdbd3220510b6f998c9 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 15 Dec 2023 10:36:02 -0800 Subject: [PATCH 1/8] Staging the 1.24.0 release (#613) --- CHANGELOG.md | 25 +++- schema-next.yaml | 22 ++-- schemas/1.24.0 | 306 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 339 insertions(+), 14 deletions(-) create mode 100644 schemas/1.24.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index 060ad26619..b194683012 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,17 +7,20 @@ release. ## Unreleased -- Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations - ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) -- Move Exceptions to attribute registry - ([#574](https://github.com/open-telemetry/semantic-conventions/pull/574)) +### Breaking + +### Features + +### Fixes + +## v1.24.0 (2023-12-15) ### Breaking - Update `jvm.gc.duration` histogram buckets to `[ 0.01, 0.1, 1, 10 ]` ([#317](https://github.com/open-telemetry/semantic-conventions/pull/317)) - BREAKING: Change type of `host.cpu.model.id` and `host.cpu.model.family` to string. - ([#495](https://github.com/open-telemetry/semantic-conventions/issues/495)) + ([#499](https://github.com/open-telemetry/semantic-conventions/pull/499)) - Changed `messaging.system` attribute type to an open enum ([#517](https://github.com/open-telemetry/semantic-conventions/pull/517)) - Rename metrics `jvm.memory.usage` to `jvm.memory.used` and `jvm.memory.usage_after_last_gc` @@ -28,11 +31,17 @@ release. - BREAKING: Change `system.disk.io.direction` and `system.network.io.direction` to global attributes `disk.io.direction` and `network.io.direction` ([#530](https://github.com/open-telemetry/semantic-conventions/pull/530)) +- BREAKING: Change `messaging.kafka.partition` to `messaging.kafka.destination.partition` + ([#547](https://github.com/open-telemetry/semantic-conventions/pull/547)) ### Features - Adds `labels` attribute to `k8s.pod` resource ([#494](https://github.com/open-telemetry/semantic-conventions/pull/494)) +- Change Erlang managed thread attribute to be the Erlang process + ([#491](https://github.com/open-telemetry/semantic-conventions/pull/491)) +- Add gcp_pubsub as a messaging system + ([#490](https://github.com/open-telemetry/semantic-conventions/pull/490)) - Adds `annotation` attribute to `k8s.pod` resource ([#494](https://github.com/open-telemetry/semantic-conventions/pull/573)) - Add `code.stacktrace` attribute @@ -52,8 +61,14 @@ release. ([#163](https://github.com/open-telemetry/semantic-conventions/pull/163)) - Add .NET 8.0 metrics for HTTP client, ASP.NET Core, SignalR server and Kestrel. ([#283](https://github.com/open-telemetry/semantic-conventions/pull/283)) +- Add system shared IO direction attributes + ([#530](https://github.com/open-telemetry/semantic-conventions/pull/530)) - JVM metrics marked stable ([#569](https://github.com/open-telemetry/semantic-conventions/pull/569)) +- Add attribute for k8s pod annotations + ([#573](https://github.com/open-telemetry/semantic-conventions/pull/573)) +- Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations + ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354)) ### Fixes diff --git a/schema-next.yaml b/schema-next.yaml index 834bff8780..d2ff748f49 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,15 +2,19 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: - # https://github.com/open-telemetry/semantic-conventions/pull/536 - - rename_metrics: - jvm.memory.usage: jvm.memory.used - jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc - # https://github.com/open-telemetry/semantic-conventions/pull/530 - - rename_attributes: - attribute_map: - system.network.io.direction: network.io.direction - system.disk.io.direction: disk.io.direction + 1.24.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.1: 1.23.0: metrics: changes: diff --git a/schemas/1.24.0 b/schemas/1.24.0 new file mode 100644 index 0000000000..f1de094f68 --- /dev/null +++ b/schemas/1.24.0 @@ -0,0 +1,306 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.24.0 +versions: + 1.24.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.1: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: From fb485c9434439946ef63a2d62589ff50807cafe1 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 19 Dec 2023 07:37:44 -0800 Subject: [PATCH 2/8] Editorial: change "J9" to "OpenJ9" (#611) Co-authored-by: Josh Suereth --- docs/runtime/jvm-metrics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index eb72b18211..7c913815e2 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -283,7 +283,7 @@ This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https: This metric is [recommended][MetricRecommended]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9. +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on OpenJ9. | Name | Instrument Type | Unit (UCUM) | Description | @@ -313,7 +313,7 @@ Note that this is always an integer value (i.e. fractional or millicores are not This metric is [recommended][MetricRecommended]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. +and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on OpenJ9. Note that the JVM does not provide a definition of what "recent" means. @@ -364,7 +364,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle This metric is [Opt-In][MetricOptIn]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, -and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9. +and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on OpenJ9. | Name | Instrument Type | Unit (UCUM) | Description | From 705155140048f518406958bbb9b7283be4c95f26 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Wed, 20 Dec 2023 11:51:13 -0600 Subject: [PATCH 3/8] Rename system.processes.* namespace to system.process.* (#484) Signed-off-by: ChrsMark Co-authored-by: Joao Grassi --- CHANGELOG.md | 3 +++ docs/system/system-metrics.md | 24 ++++++++++++------------ model/metrics/system-metrics.yaml | 16 ++++++++-------- schema-next.yaml | 11 +++++++++++ 4 files changed, 34 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b194683012..6b62c84eb6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. ### Breaking +- Rename `system.processes.*` namespace to `system.process.*` + ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) + ### Features ### Fixes diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index d39384babc..59dd808491 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -52,8 +52,8 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam * [Metric: `system.network.io`](#metric-systemnetworkio) * [Metric: `system.network.connections`](#metric-systemnetworkconnections) - [Aggregate System Process Metrics](#aggregate-system-process-metrics) - * [Metric: `system.processes.count`](#metric-systemprocessescount) - * [Metric: `system.processes.created`](#metric-systemprocessescreated) + * [Metric: `system.process.count`](#metric-systemprocesscount) + * [Metric: `system.process.created`](#metric-systemprocesscreated) - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) * [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable) @@ -718,22 +718,22 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **Description:** System level aggregate process metrics captured under the namespace `system.process`. For metrics at the individual process level, see [process metrics](process-metrics.md). -### Metric: `system.processes.count` +### Metric: `system.process.count` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `system.processes.count` | UpDownCounter | `{process}` | Total number of processes in each state | +| `system.process.count` | UpDownCounter | `{process}` | Total number of processes in each state | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `system.processes.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | Recommended | +| `system.process.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | Recommended | -`system.processes.status` 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. +`system.process.status` 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 | |---|---| @@ -743,17 +743,17 @@ This metric is [recommended][MetricRecommended]. | `defunct` | defunct | -### Metric: `system.processes.created` +### Metric: `system.process.created` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `system.processes.created` | Counter | `{process}` | Total number of processes created over uptime of the host | +| `system.process.created` | Counter | `{process}` | Total number of processes created over uptime of the host | - + ## `system.{os}.` - OS Specific System Metrics diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index d411115ea8..9f288e87ff 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -447,9 +447,9 @@ groups: - ref: system.network.state - ref: network.transport - # system.processes.* metrics and attribute group - - id: attributes.system.processes - prefix: system.processes + # system.process.* metrics and attribute group + - id: attributes.system.process + prefix: system.process type: attribute_group brief: "Describes System Process metric attributes" attributes: @@ -470,18 +470,18 @@ groups: examples: ["running"] - - id: metric.system.processes.count + - id: metric.system.process.count type: metric - metric_name: system.processes.count + metric_name: system.process.count brief: "Total number of processes in each state" instrument: updowncounter unit: "{process}" attributes: - - ref: system.processes.status + - ref: system.process.status - - id: metric.system.processes.created + - id: metric.system.process.created type: metric - metric_name: system.processes.created + metric_name: system.process.created brief: "Total number of processes created over uptime of the host" instrument: counter unit: "{process}" diff --git a/schema-next.yaml b/schema-next.yaml index d2ff748f49..aca72805d2 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,17 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/484 + - rename_attributes: + attribute_map: + system.processes.status: system.process.status + apply_to_metrics: + - system.processes.count + - rename_metrics: + system.processes.count: system.process.count + system.processes.created: system.process.created 1.24.0: metrics: changes: From 9423bd3a0b3efb6b3664b574f094b54f03e83b31 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Tue, 2 Jan 2024 12:31:26 -0600 Subject: [PATCH 4/8] Reflect service.*, telemetry.sdk.* stability in model (#620) --- docs/resource/README.md | 10 +++++----- model/resource/service.yaml | 2 ++ model/resource/telemetry.yaml | 3 +++ 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/resource/README.md b/docs/resource/README.md index 5a12b18593..a77cbd2f69 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -82,8 +82,8 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required | -| `service.version` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | Recommended | +| `service.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Logical name of the service. [1] | `shoppingcart` | Required | +| `service.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | Recommended | **[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. @@ -132,9 +132,9 @@ service.name = Shop.shoppingcart | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | -| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required | +| `telemetry.sdk.language` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The language of the telemetry SDK. | `cpp` | Required | +| `telemetry.sdk.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | +| `telemetry.sdk.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The version string of the telemetry SDK. | `1.2.3` | Required | **[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the diff --git a/model/resource/service.yaml b/model/resource/service.yaml index e930b62194..05b2e02698 100644 --- a/model/resource/service.yaml +++ b/model/resource/service.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: name type: string + stability: stable requirement_level: required brief: > Logical name of the service. @@ -18,6 +19,7 @@ groups: examples: ["shoppingcart"] - id: version type: string + stability: stable brief: > The version string of the service API or implementation. The format is not defined by these conventions. examples: ["2.0.0", "a01dbef8a"] diff --git a/model/resource/telemetry.yaml b/model/resource/telemetry.yaml index 6966b4a853..9b57a7afd2 100644 --- a/model/resource/telemetry.yaml +++ b/model/resource/telemetry.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: sdk.name type: string + stability: stable requirement_level: required brief: > The name of the telemetry SDK as defined above. @@ -46,11 +47,13 @@ groups: value: "swift" - id: webjs value: "webjs" + stability: stable requirement_level: required brief: > The language of the telemetry SDK. - id: sdk.version type: string + stability: stable requirement_level: required brief: > The version string of the telemetry SDK. From 3a9d477cf596d2317a35becf952210e739d0c56a Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 4 Jan 2024 13:02:35 -0500 Subject: [PATCH 5/8] Stabilize exception semantic conventions. (#619) --- docs/attributes-registry/exception.md | 8 ++++---- docs/exceptions/exceptions-logs.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- model/registry/exception.yaml | 4 ++++ 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/exception.md b/docs/attributes-registry/exception.md index e3874f51ba..e5d541c930 100644 --- a/docs/attributes-registry/exception.md +++ b/docs/attributes-registry/exception.md @@ -8,10 +8,10 @@ | Attribute | Type | Description | Examples | |---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | -| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | +| `exception.escaped` | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | +| `exception.message` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| `exception.stacktrace` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | +| `exception.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | **[1]:** An exception is considered to have escaped (or left) the scope of a span, if that span is ended while the exception is still logically "in flight". diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index 19c7c253dd..11656ea1df 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -4,7 +4,7 @@ linkTitle: Logs # Semantic Conventions for Exceptions in Logs -**Status**: [Experimental][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording exceptions on [logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/logs/event-api.md#emit-event) diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 31f88edb53..18a91996a5 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -4,7 +4,7 @@ linkTitle: Spans # Semantic Conventions for Exceptions on Spans -**Status**: [Experimental][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording application exceptions associated with spans. diff --git a/model/registry/exception.yaml b/model/registry/exception.yaml index 8894b316a3..7e1b011889 100644 --- a/model/registry/exception.yaml +++ b/model/registry/exception.yaml @@ -8,6 +8,7 @@ groups: attributes: - id: type type: string + stability: stable brief: > The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type @@ -15,10 +16,12 @@ groups: examples: ["java.net.ConnectException", "OSError"] - id: message type: string + stability: stable brief: The exception message. examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] - id: stacktrace type: string + stability: stable brief: > A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. @@ -28,6 +31,7 @@ groups: at com.example.GenerateTrace.main(GenerateTrace.java:5)' - id: escaped type: boolean + stability: stable brief: > SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. From 7d0c0a0fc5298362cffcd9b1d79c9a0716e58f52 Mon Sep 17 00:00:00 2001 From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com> Date: Mon, 8 Jan 2024 18:30:43 +0100 Subject: [PATCH 6/8] Refactoring: move browser to the registry (#605) Co-authored-by: Joao Grassi --- docs/attributes-registry/README.md | 1 + docs/attributes-registry/browser.md | 24 +++++++++++++++ docs/resource/browser.md | 8 ++--- model/registry/browser.yaml | 47 +++++++++++++++++++++++++++++ model/resource/browser.yaml | 44 +++------------------------ 5 files changed, 80 insertions(+), 44 deletions(-) create mode 100644 docs/attributes-registry/browser.md create mode 100644 model/registry/browser.yaml diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 89818c8380..ada3b9534f 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -27,6 +27,7 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: +* [Browser](browser.md) * [Client](client.md) * [Cloud](cloud.md) * [Code](code.md) diff --git a/docs/attributes-registry/browser.md b/docs/attributes-registry/browser.md new file mode 100644 index 0000000000..84366ea986 --- /dev/null +++ b/docs/attributes-registry/browser.md @@ -0,0 +1,24 @@ + + +# Browser + +## Browser Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | +| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | +| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | +| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | + +**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). + +**[2]:** This value is intended to be taken from the Navigator API `navigator.language`. + +**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. + +**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. + diff --git a/docs/resource/browser.md b/docs/resource/browser.md index cec3fe9494..da7818bb5f 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -11,10 +11,10 @@ All of these attributes can be provided by the user agent itself in the form of | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended | -| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | -| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | -| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended | +| [`browser.brands`](../attributes-registry/browser.md) | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended | +| [`browser.language`](../attributes-registry/browser.md) | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | +| [`browser.mobile`](../attributes-registry/browser.md) | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | +| [`browser.platform`](../attributes-registry/browser.md) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended | | [`user_agent.original`](../attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended | **[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). diff --git a/model/registry/browser.yaml b/model/registry/browser.yaml new file mode 100644 index 0000000000..e9d0da5c93 --- /dev/null +++ b/model/registry/browser.yaml @@ -0,0 +1,47 @@ +groups: + - id: registry.browser + prefix: browser + type: resource + brief: > + The web browser attributes + attributes: + - id: brands + type: string[] + brief: 'Array of brand name and version separated by a space' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.brands`). + examples: [ " Not A;Brand 99", "Chromium 99", "Chrome 99" ] + - id: platform + type: string + brief: 'The platform on which the browser is running' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.platform`). If unavailable, the legacy + `navigator.platform` API SHOULD NOT be used instead and this attribute + SHOULD be left unset in order for the values to be consistent. + + The list of possible values is defined in the + [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). + Note that some (but not all) of these values can overlap with values + in the [`os.type` and `os.name` attributes](./os.md). + However, for consistency, the values in the `browser.platform` attribute + should capture the exact value that the user agent provides. + examples: ['Windows', 'macOS', 'Android'] + - id: mobile + type: boolean + brief: 'A boolean that is true if the browser is running on a mobile device' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.mobile`). If unavailable, this attribute + SHOULD be left unset. + - id: language + type: string + brief: 'Preferred language of the user using the browser' + note: > + This value is intended to be taken from the Navigator API + `navigator.language`. + examples: ["en", "en-US", "fr", "fr-FR"] diff --git a/model/resource/browser.yaml b/model/resource/browser.yaml index 56830c1dde..0ec1a6e3aa 100644 --- a/model/resource/browser.yaml +++ b/model/resource/browser.yaml @@ -7,46 +7,10 @@ groups: The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device). attributes: - - id: brands - type: string[] - brief: 'Array of brand name and version separated by a space' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.brands`). - examples: [" Not A;Brand 99", "Chromium 99", "Chrome 99"] - - id: platform - type: string - brief: 'The platform on which the browser is running' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.platform`). If unavailable, the legacy - `navigator.platform` API SHOULD NOT be used instead and this attribute - SHOULD be left unset in order for the values to be consistent. - - The list of possible values is defined in the - [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). - Note that some (but not all) of these values can overlap with values - in the [`os.type` and `os.name` attributes](./os.md). - However, for consistency, the values in the `browser.platform` attribute - should capture the exact value that the user agent provides. - examples: ['Windows', 'macOS', 'Android'] - - id: mobile - type: boolean - brief: 'A boolean that is true if the browser is running on a mobile device' - note: > - This value is intended to be taken from the - [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) - (`navigator.userAgentData.mobile`). If unavailable, this attribute - SHOULD be left unset. - - id: language - type: string - brief: 'Preferred language of the user using the browser' - note: > - This value is intended to be taken from the Navigator API - `navigator.language`. - examples: ["en", "en-US", "fr", "fr-FR"] + - ref: browser.brands + - ref: browser.platform + - ref: browser.mobile + - ref: browser.language - ref: user_agent.original brief: 'Full user-agent string provided by the browser' note: > From 1dd4fe343906a4735f50da471d63719dd0dfd922 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 8 Jan 2024 14:29:17 -0800 Subject: [PATCH 7/8] Add HTTP semantic convention stability migration guide (#612) --- .markdown_link_check_config.json | 2 +- docs/http/migration-guide.md | 223 +++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 docs/http/migration-guide.md diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index 48c1f6c392..efd4eb0d85 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -10,7 +10,7 @@ "replacement": "{{BASEURL}}/" }, { - "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/[^/]+/docs/", + "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/[^v][^/]*/docs/", "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/" } ], diff --git a/docs/http/migration-guide.md b/docs/http/migration-guide.md new file mode 100644 index 0000000000..16336c73b3 --- /dev/null +++ b/docs/http/migration-guide.md @@ -0,0 +1,223 @@ +# HTTP semantic convention stability migration guide + +Due to the significant number of modifications and the extensive user base +affected by them, existing HTTP instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable HTTP semantic conventions. + +Specifically, when existing HTTP instrumentations published by OpenTelemetry are +updated to the stable HTTP semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `http` - emit the stable HTTP and networking conventions, and stop emitting + the old HTTP and networking conventions that the instrumentation emitted + previously. + - `http/dup` - emit both the old and the stable HTTP and networking + conventions, allowing for a phased rollout of the stable semantic + conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old HTTP and networking conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable HTTP and networking conventions. + +## Summary of changes + +This section summarizes the changes made to the HTTP semantic conventions +from +[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +to +[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md). + +### Common attributes across HTTP client and server spans + + +| Change | Comments | +| --- | --- | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default (configurable) plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `http.request.header.` | • Dash (`"-"`) to underscore (`"_"`) normalization in `` has been removed
• On HTTP server spans: now must be provided to sampler | +| `http.response.header.` | Dash (`"-"`) to underscore (`"_"`) normalization in `` has been removed | +| `http.request_content_length` → `http.request.body.size` | • Recommended → Opt-In
• _Not marked stable yet_ | +| `http.response_content_length` → `http.response.body.size` | • Recommended → Opt-In
• _Not marked stable yet_ | +| `user_agent.original` | • On HTTP client spans: Recommended → Opt-In
• On HTTP server spans: now must be provided to sampler
• See note if [migrating from <= v1.18.0](#migrating-from--v1180) | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | • Examples fixed: `2.0` → `2` and `3.0` → `3`
• See note if [migrating from <= v1.19.0](#migrating-from--v1190) | +| `net.sock.family` | Removed | +| `net.sock.peer.addr` → `network.peer.address` | On HTTP server spans: if `http.client_ip` was unknown, then also `net.sock.peer.addr` → `client.address`; `client.address` must be provided to sampler | +| `net.sock.peer.port` → `network.peer.port` | Now captured even if same as `server.port` | +| `net.sock.peer.name` | Removed | +| New: `http.request.method_original` | Only captured when `http.request.method` is `_OTHER` | +| New: `error.type` | | + + +References: + +- [Common attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#common-attributes) +- [Common attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#common-attributes) + +### HTTP client span attributes + + +| Change | Comments | +| --- | --- | +| `http.url` → `url.full` | | +| `http.resend_count` → `http.request.resend_count` | | +| `net.peer.name` → `server.address` | | +| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme | + + +References: + +- [HTTP client span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-client) +- [HTTP client span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP server span attributes + + +| Change | Comments | +| --- | --- | +| `http.route` | No change | +| `http.target` → `url.path` and `url.query` | Split into two separate attributes | +| `http.scheme` → `url.scheme` | Now factors in [X-Forwarded-Proto][], [Forwarded#proto][] headers | +| `http.client_ip` → `client.address` | If `http.client_ip` was unknown (i.e., no [X-Forwarded-For][], [Forwarded#for][] headers), then `net.sock.peer.addr` → `client.address`; now must be provided to sampler | +| `net.host.name` → `server.address` | Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][], [Forwarded#host][] headers | +| `net.host.port` → `server.port` | Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][X-Forwarded-Host], [Forwarded#host][] headers | + + +References: + +- [HTTP server span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-server) +- [HTTP server span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP client and server span names + +The `{http.method}` portion of span names is replace by `HTTP` when +`{http.method}` is `_OTHER`. + +See note if [migrating from `<= v1.17.0`](#migrating-from--v1170). + +References: + +- [HTTP client and server span names v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#name) +- [HTTP client and server span names v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration) + +### HTTP client duration metric + +Metric changes: + +- **Name**: `http.client.duration` → `http.client.request.duration` +- **Unit**: `ms` → `s` +- **Description**: `Measures the duration of inbound HTTP requests.` → + `Duration of HTTP server requests.` +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds, and zero bucket boundary removed +- **Attributes**: see table below + + +| Attribute change | Comments | +| --- | --- | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `net.peer.name` → `server.address` | | +| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme | +| `net.sock.peer.addr` | Removed | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) | +| New: `error.type` | | + + +References: + +- [Metric `http.client.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientduration) +- [Metric `http.client.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration) + +### HTTP server duration metric + +Metric changes: + +- **Name**: `http.server.duration` → `http.server.request.duration` +- **Unit**: `ms` → `s` +- **Description**: `Measures the duration of inbound HTTP requests.` → + `Duration of HTTP server requests.` +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds, and zero bucket boundary removed +- **Attributes**: see table below + + +| Attribute change | Comments | +| --- | --- | +| `http.route` | No change | +| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` | +| `http.status_code` → `http.response.status_code` | | +| `http.scheme` → `url.scheme` | Now factors in [`X-Forwarded-Proto` span][X-Forwarded-Proto], [`Forwarded#proto` span][Forwarded#proto] headers | +| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set | +| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) | +| `net.host.name` → `server.address` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers | +| `net.host.port` → `server.port` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers | +| New: `error.type` | | + + +References: + +- [Metric `http.server.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpserverduration) +- [Metric `http.server.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration) + +## Migrating from a version prior to v1.20.0? + +In addition to the changes made to the HTTP semantic conventions +from +[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +to +[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md), +there are additional changes if you are migrating to v1.23.1 from a version prior to v1.20.0. + +### Migrating from `<= v1.19.0` + +- `http.flavor` → `network.protocol.version` + - Examples fixed: `2.0` → `2` and `3.0` → `3` + +### Migrating from `<= v1.18.0` + +- `http.user_agent` → `user_agent.original` + +### Migrating from `<= v1.17.0` + +#### HTTP server span name + +- When `http.route` is available:
`{http.route}` → + `{summary} {http.route}` +- When `http.route` is not available:
`HTTP {http.method}` → + `{summary}` + +Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in +which case `{summary}` is `HTTP`. + +#### HTTP client span name + +- `HTTP {http.method}` → `{summary}` + +Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in +which case `{summary}` is `HTTP`. + +### Migrating from `<= v1.16.0` + +This document does not cover these versions. + +[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4 +[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1 +[Forwarded#for]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for +[Forwarded#proto]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto +[Forwarded#host]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host +[X-Forwarded-For]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For +[X-Forwarded-Proto]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto +[X-Forwarded-Host]: +https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host From 75f9d428a45f9e779b72c34d9ac3c00625b7472a Mon Sep 17 00:00:00 2001 From: Dmitrii Anoshin Date: Mon, 8 Jan 2024 14:31:40 -0800 Subject: [PATCH 8/8] Add a warning to the system semantic conventions (#579) --- docs/system/hardware-metrics.md | 11 +++++++++++ docs/system/process-metrics.md | 10 ++++++++++ docs/system/system-metrics.md | 10 ++++++++++ 3 files changed, 31 insertions(+) diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 904dd8c74d..09ba773b65 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -33,6 +33,17 @@ when creating instruments not explicitly defined in the specification. +> **Warning** +> Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/hardware-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. + ## Common hardware attributes All metrics in `hw.` instruments should be attached to a [Host Resource](/docs/resource/host.md) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 4312631963..c619763717 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -25,6 +25,16 @@ metrics](/docs/runtime/README.md#metrics). +> **Warning** Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/process-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. + ## Metric Instruments ### Process diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 59dd808491..4f682cc030 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -59,6 +59,16 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam +> **Warning** Existing instrumentations and collector that are using +> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/system-metrics.md) +> (or prior): +> +> * SHOULD NOT adopt any breaking changes from document until the system +> semantic conventions are marked stable. Conventions include, but are not +> limited to, attributes, metric names, and unit of measure. +> * SHOULD introduce a control mechanism to allow users to opt-in to the new +> conventions once the migration plan is finalized. + ## Processor Metrics **Description:** System level processor metrics captured under the namespace `system.cpu`.