From c83a10a9c33c18a769835e959200d0e24dc708fe Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 15 Aug 2023 04:33:53 -0700 Subject: [PATCH 01/25] Move network attributes out of trace folder (#256) --- model/{trace/general.yaml => network.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename model/{trace/general.yaml => network.yaml} (100%) diff --git a/model/trace/general.yaml b/model/network.yaml similarity index 100% rename from model/trace/general.yaml rename to model/network.yaml From 0669ca5b81d366dc21647b8ed967194bb0868a4c Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 16 Aug 2023 14:59:43 -0700 Subject: [PATCH 02/25] Add `jvm.cpu.count` metric (#52) Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 ++ docs/system/runtime-environment-metrics.md | 16 ++++++++++++++++ model/metrics/process-runtime-jvm-metrics.yaml | 7 +++++++ 3 files changed, 25 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8c5f52301..a79fc4b3d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,8 @@ release. - Clarify that `http/dup` has higher precedence than `http` in case both values are present in `OTEL_SEMCONV_STABILITY_OPT_IN` ([#249](https://github.com/open-telemetry/semantic-conventions/pull/249)) +- Add `jvm.cpu.count` metric. + ([#52](https://github.com/open-telemetry/semantic-conventions/pull/52)) ## v1.21.0 (2023-07-13) diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index c0843daf01..b3c7b8cb88 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -30,6 +30,7 @@ semantic conventions when instrumenting runtime environments. * [Metric: `jvm.classes.unloaded`](#metric-jvmclassesunloaded) * [Metric: `jvm.classes.current_loaded`](#metric-jvmclassescurrent_loaded) * [Metric: `jvm.cpu.time`](#metric-jvmcputime) + * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) - [JVM Metrics (Experimental)](#jvm-metrics-experimental) * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) @@ -289,6 +290,21 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https: +### Metric: `jvm.cpu.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). +Note that this is always an integer value (i.e. fractional or millicores are not represented). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | + + + + + ### Metric: `jvm.cpu.recent_utilization` This metric is [recommended][MetricRecommended]. diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml index d6b4c502a8..683b42ba92 100644 --- a/model/metrics/process-runtime-jvm-metrics.yaml +++ b/model/metrics/process-runtime-jvm-metrics.yaml @@ -114,6 +114,13 @@ groups: instrument: updowncounter unit: "{class}" + - id: metric.jvm.cpu.count + type: metric + metric_name: jvm.cpu.count + brief: "Number of processors available to the Java virtual machine." + instrument: updowncounter + unit: "{cpu}" + - id: metric.jvm.cpu.time type: metric metric_name: jvm.cpu.time From 3bd1c39e5f6aae7ea942c50bd771fa2e7e408249 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 16 Aug 2023 16:01:04 -0700 Subject: [PATCH 03/25] Rename `jvm.classes.current_loaded` to `jvm.classes.count` (#60) --- CHANGELOG.md | 2 ++ docs/system/runtime-environment-metrics.md | 10 +++++----- model/metrics/process-runtime-jvm-metrics.yaml | 4 ++-- schema-next.yaml | 3 ++- 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a79fc4b3d6..054066f8fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,8 @@ release. ([#249](https://github.com/open-telemetry/semantic-conventions/pull/249)) - Add `jvm.cpu.count` metric. ([#52](https://github.com/open-telemetry/semantic-conventions/pull/52)) +- BREAKING: Rename `jvm.classes.current_loaded` metrics to `jvm.classes.count` + ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) ## v1.21.0 (2023-07-13) diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index b3c7b8cb88..e884bf5765 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -28,7 +28,7 @@ semantic conventions when instrumenting runtime environments. * [Metric: `jvm.threads.count`](#metric-jvmthreadscount) * [Metric: `jvm.classes.loaded`](#metric-jvmclassesloaded) * [Metric: `jvm.classes.unloaded`](#metric-jvmclassesunloaded) - * [Metric: `jvm.classes.current_loaded`](#metric-jvmclassescurrent_loaded) + * [Metric: `jvm.classes.count`](#metric-jvmclassescount) * [Metric: `jvm.cpu.time`](#metric-jvmcputime) * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) @@ -260,18 +260,18 @@ This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](http -### Metric: `jvm.classes.current_loaded` +### Metric: `jvm.classes.count` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | +| `jvm.classes.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | - + ### Metric: `jvm.cpu.time` diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml index 683b42ba92..5008665b6b 100644 --- a/model/metrics/process-runtime-jvm-metrics.yaml +++ b/model/metrics/process-runtime-jvm-metrics.yaml @@ -107,9 +107,9 @@ groups: instrument: counter unit: "{class}" - - id: metric.jvm.classes.current_loaded + - id: metric.jvm.classes.count type: metric - metric_name: jvm.classes.current_loaded + metric_name: jvm.classes.count brief: "Number of classes currently loaded." instrument: updowncounter unit: "{class}" diff --git a/schema-next.yaml b/schema-next.yaml index e19ff8a65e..bb558406e4 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -18,7 +18,8 @@ versions: process.runtime.jvm.threads.count: jvm.threads.count process.runtime.jvm.classes.loaded: jvm.classes.loaded process.runtime.jvm.classes.unloaded: jvm.classes.unloaded - process.runtime.jvm.classes.current_loaded: jvm.classes.current_loaded + # https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.classes.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 From a42aecc6b8e2a374027419ce590d856909c953bb Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 17 Aug 2023 04:15:20 -0700 Subject: [PATCH 04/25] Rename jvm.buffer.(usage|limit) to jvm.buffer.memory.(usage|limit) (#253) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ docs/system/runtime-environment-metrics.md | 20 +++++++++---------- ...cess-runtime-jvm-metrics-experimental.yaml | 8 ++++---- schema-next.yaml | 6 ++++-- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 054066f8fe..bcee1a1486 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,9 @@ release. ([#249](https://github.com/open-telemetry/semantic-conventions/pull/249)) - Add `jvm.cpu.count` metric. ([#52](https://github.com/open-telemetry/semantic-conventions/pull/52)) +- BREAKING: Rename metrics `jvm.buffer.usage` to `jvm.buffer.memory.usage` + and `jvm.buffer.limit` to `jvm.buffer.memory.limit`. + ([#253](https://github.com/open-telemetry/semantic-conventions/pull/253)) - BREAKING: Rename `jvm.classes.current_loaded` metrics to `jvm.classes.count` ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index e884bf5765..9967d03805 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -36,8 +36,8 @@ semantic conventions when instrumenting runtime environments. * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) - * [Metric: `jvm.buffer.usage`](#metric-jvmbufferusage) - * [Metric: `jvm.buffer.limit`](#metric-jvmbufferlimit) + * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -387,18 +387,18 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht -### Metric: `jvm.buffer.usage` +### Metric: `jvm.buffer.memory.usage` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | +| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | @@ -406,18 +406,18 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). -### Metric: `jvm.buffer.limit` +### Metric: `jvm.buffer.memory.limit` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | +| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/process-runtime-jvm-metrics-experimental.yaml index da74d34423..8ea4fa57c5 100644 --- a/model/metrics/process-runtime-jvm-metrics-experimental.yaml +++ b/model/metrics/process-runtime-jvm-metrics-experimental.yaml @@ -45,17 +45,17 @@ groups: Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - id: metric.jvm.buffer.usage + - id: metric.jvm.buffer.memory.usage type: metric - metric_name: jvm.buffer.usage + metric_name: jvm.buffer.memory.usage extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." instrument: updowncounter unit: "By" - - id: metric.jvm.buffer.limit + - id: metric.jvm.buffer.memory.limit type: metric - metric_name: jvm.buffer.limit + metric_name: jvm.buffer.memory.limit extends: attributes.jvm.buffer brief: "Measure of total memory capacity of buffers." instrument: updowncounter diff --git a/schema-next.yaml b/schema-next.yaml index bb558406e4..7c3c73c3d6 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -25,8 +25,10 @@ versions: 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 - process.runtime.jvm.buffer.usage: jvm.buffer.usage - process.runtime.jvm.buffer.limit: jvm.buffer.limit + # 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: From 098db1ca510da01fe941f6c6308aad5000def910 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 17 Aug 2023 08:45:02 -0700 Subject: [PATCH 05/25] Remove pluralization from JVM metric namespaces (#252) --- CHANGELOG.md | 2 + docs/system/runtime-environment-metrics.md | 40 +++++++++---------- .../metrics/process-runtime-jvm-metrics.yaml | 16 ++++---- schema-next.yaml | 14 ++++--- 4 files changed, 39 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bcee1a1486..006acac363 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -55,6 +55,8 @@ release. ([#253](https://github.com/open-telemetry/semantic-conventions/pull/253)) - BREAKING: Rename `jvm.classes.current_loaded` metrics to `jvm.classes.count` ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) +- BREAKING: Remove pluralization from JVM metric namespaces. + ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) ## v1.21.0 (2023-07-13) diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index 9967d03805..c8b8ce25a9 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -25,10 +25,10 @@ semantic conventions when instrumenting runtime environments. * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) - * [Metric: `jvm.threads.count`](#metric-jvmthreadscount) - * [Metric: `jvm.classes.loaded`](#metric-jvmclassesloaded) - * [Metric: `jvm.classes.unloaded`](#metric-jvmclassesunloaded) - * [Metric: `jvm.classes.count`](#metric-jvmclassescount) + * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) + * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) + * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) + * [Metric: `jvm.class.count`](#metric-jvmclasscount) * [Metric: `jvm.cpu.time`](#metric-jvmcputime) * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) @@ -213,65 +213,65 @@ of `[]` (single bucket histogram capturing count, sum, min, max). **[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). -### Metric: `jvm.threads.count` +### Metric: `jvm.thread.count` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and [`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). Note that this is the number of platform threads (as opposed to virtual threads). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | +| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | -### Metric: `jvm.classes.loaded` +### Metric: `jvm.class.loaded` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | +| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - + -### Metric: `jvm.classes.unloaded` +### Metric: `jvm.class.unloaded` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | +| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - + -### Metric: `jvm.classes.count` +### Metric: `jvm.class.count` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `jvm.classes.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | +| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | - + ### Metric: `jvm.cpu.time` diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml index 5008665b6b..4306fc239c 100644 --- a/model/metrics/process-runtime-jvm-metrics.yaml +++ b/model/metrics/process-runtime-jvm-metrics.yaml @@ -83,9 +83,9 @@ groups: Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - id: metric.jvm.threads.count + - id: metric.jvm.thread.count type: metric - metric_name: jvm.threads.count + metric_name: jvm.thread.count brief: "Number of executing platform threads." instrument: updowncounter unit: "{thread}" @@ -93,23 +93,23 @@ groups: - ref: thread.daemon requirement_level: recommended - - id: metric.jvm.classes.loaded + - id: metric.jvm.class.loaded type: metric - metric_name: jvm.classes.loaded + metric_name: jvm.class.loaded brief: "Number of classes loaded since JVM start." instrument: counter unit: "{class}" - - id: metric.jvm.classes.unloaded + - id: metric.jvm.class.unloaded type: metric - metric_name: jvm.classes.unloaded + metric_name: jvm.class.unloaded brief: "Number of classes unloaded since JVM start." instrument: counter unit: "{class}" - - id: metric.jvm.classes.count + - id: metric.jvm.class.count type: metric - metric_name: jvm.classes.count + metric_name: jvm.class.count brief: "Number of classes currently loaded." instrument: updowncounter unit: "{class}" diff --git a/schema-next.yaml b/schema-next.yaml index 7c3c73c3d6..acc97ca7b8 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -15,11 +15,15 @@ versions: 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 - process.runtime.jvm.threads.count: jvm.threads.count - process.runtime.jvm.classes.loaded: jvm.classes.loaded - process.runtime.jvm.classes.unloaded: jvm.classes.unloaded - # https://github.com/open-telemetry/semantic-conventions/pull/60 - process.runtime.jvm.classes.current_loaded: jvm.classes.count + # 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 From 99f3f9d4aff8afb94dd2f09f7cde73dbfd0335fc Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 21 Aug 2023 07:26:07 -0700 Subject: [PATCH 06/25] Move JVM metrics to their own page (#271) --- docs/jvm/jvm-metrics.md | 430 ++++++++++++++++++ docs/system/runtime-environment-metrics.md | 392 ---------------- ...tal.yaml => jvm-metrics-experimental.yaml} | 0 ...time-jvm-metrics.yaml => jvm-metrics.yaml} | 0 4 files changed, 430 insertions(+), 392 deletions(-) create mode 100644 docs/jvm/jvm-metrics.md rename model/metrics/{process-runtime-jvm-metrics-experimental.yaml => jvm-metrics-experimental.yaml} (100%) rename model/metrics/{process-runtime-jvm-metrics.yaml => jvm-metrics.yaml} (100%) diff --git a/docs/jvm/jvm-metrics.md b/docs/jvm/jvm-metrics.md new file mode 100644 index 0000000000..6272e494fe --- /dev/null +++ b/docs/jvm/jvm-metrics.md @@ -0,0 +1,430 @@ + + +# Semantic Conventions for JVM Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for JVM metrics in OpenTelemetry. + + + + + +- [JVM Memory](#jvm-memory) + * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) + * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) + * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) + * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) +- [JVM Garbage Collection](#jvm-garbage-collection) + * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) +- [JVM Threads](#jvm-threads) + * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) +- [JVM Classes](#jvm-classes) + * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) + * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) + * [Metric: `jvm.class.count`](#metric-jvmclasscount) +- [JVM CPU](#jvm-cpu) + * [Metric: `jvm.cpu.time`](#metric-jvmcputime) + * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) + * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) +- [Very experimental](#very-experimental) + * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) + * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) + * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) + * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) + * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) + + + +## JVM Memory + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.memory.*` + +### Metric: `jvm.memory.usage` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.committed` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.memory.usage_after_last_gc` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +## JVM Garbage Collection + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.gc.*` + +### Metric: `jvm.gc.duration` + +This metric is [recommended][MetricRecommended]. +This metric is obtained by subscribing to +[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) +of `[]` (single bucket histogram capturing count, sum, min, max). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | +| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | + +**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). + +**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + + +## JVM Threads + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.thread.*` + +### Metric: `jvm.thread.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and +[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). +Note that this is the number of platform threads (as opposed to virtual threads). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | + + +## JVM Classes + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.class.*` + +### Metric: `jvm.class.loaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | + + + + + +### Metric: `jvm.class.unloaded` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | + + + + + +### Metric: `jvm.class.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | + + + + + +## JVM CPU + +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.cpu.*` + +### Metric: `jvm.cpu.time` + +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. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | + + + + + +### Metric: `jvm.cpu.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). +Note that this is always an integer value (i.e. fractional or millicores are not represented). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | + + + + + +### Metric: `jvm.cpu.recent_utilization` + +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. +Note that the JVM does not provide a definition of what "recent" means. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). + + + + + +## Very experimental + +**Description:** Very experimental Java Virtual Machine (JVM) metrics captured under `jvm.` + +### Metric: `jvm.memory.init` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | +| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | + +**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). + +`jvm.memory.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `jvm.system.cpu.utilization` + +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. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). + + + + + +### Metric: `jvm.system.cpu.load_1m` + +This metric is [Opt-In][MetricOptIn]. +This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | + +**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). + + + + + +### Metric: `jvm.buffer.memory.usage` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +### Metric: `jvm.buffer.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | + +**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index c8b8ce25a9..c77222063a 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -19,26 +19,6 @@ semantic conventions when instrumenting runtime environments. - [Metric Instruments](#metric-instruments) * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) - [Attributes](#attributes) -- [JVM Metrics](#jvm-metrics) - * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) - * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) - * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) - * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) - * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) - * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) - * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) - * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) - * [Metric: `jvm.class.count`](#metric-jvmclasscount) - * [Metric: `jvm.cpu.time`](#metric-jvmcputime) - * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) - * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) -- [JVM Metrics (Experimental)](#jvm-metrics-experimental) - * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) - * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) - * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) - * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) - * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) - * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -74,376 +54,4 @@ consider, for example pthreads vs green thread implementations. [`process.runtime`](/docs/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. -## JVM Metrics - -**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.` - -### Metric: `jvm.memory.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.committed` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.memory.usage_after_last_gc` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.gc.duration` - -This metric is [recommended][MetricRecommended]. -This metric is obtained by subscribing to -[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) -of `[]` (single bucket histogram capturing count, sum, min, max). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | - -**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). - -**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - -### Metric: `jvm.thread.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and -[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). -Note that this is the number of platform threads (as opposed to virtual threads). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.thread.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | - - -### Metric: `jvm.class.loaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - - - - - -### Metric: `jvm.class.unloaded` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - - - - - -### Metric: `jvm.class.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.class.count` | UpDownCounter | `{class}` | Number of classes currently loaded. | - - - - - -### Metric: `jvm.cpu.time` - -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. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | - - - - - -### Metric: `jvm.cpu.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`Runtime#availableProcessors()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). -Note that this is always an integer value (i.e. fractional or millicores are not represented). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.count` | UpDownCounter | `{cpu}` | Number of processors available to the Java virtual machine. | - - - - - -### Metric: `jvm.cpu.recent_utilization` - -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. -Note that the JVM does not provide a definition of what "recent" means. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). - - - - - -## JVM Metrics (Experimental) - -**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.` - -### Metric: `jvm.memory.init` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`jvm.memory.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `jvm.system.cpu.utilization` - -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. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | - -**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). - - - - - -### Metric: `jvm.system.cpu.load_1m` - -This metric is [Opt-In][MetricOptIn]. -This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | - -**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). - - - - - -### Metric: `jvm.buffer.memory.usage` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `jvm.buffer.memory.limit` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.memory.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `jvm.buffer.count` - -This metric is [recommended][MetricRecommended]. -This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md -[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in -[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml similarity index 100% rename from model/metrics/process-runtime-jvm-metrics-experimental.yaml rename to model/metrics/jvm-metrics-experimental.yaml diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml similarity index 100% rename from model/metrics/process-runtime-jvm-metrics.yaml rename to model/metrics/jvm-metrics.yaml From 4bbb8c907402caa90bc077214e8a2c78807c1ab9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 22 Aug 2023 10:10:01 -0700 Subject: [PATCH 07/25] Simplify HTTP metric briefs (#276) --- CHANGELOG.md | 2 ++ docs/http/http-metrics.md | 16 ++++++++++++---- model/metrics/http.yaml | 12 ++++++++---- 3 files changed, 22 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 006acac363..6faafa19c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,8 @@ release. ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60)) - BREAKING: Remove pluralization from JVM metric namespaces. ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) +- Simplify HTTP metric briefs. + ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) ## v1.21.0 (2023-07-13) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 5f8c192706..26ad37b78e 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -214,7 +214,9 @@ This metric is optional. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.server.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | +| `http.server.request.size` | Histogram | `By` | Measures the size of HTTP request messages. [1] | + +**[1]:** Size as measured over the wire (compressed size if messages are compressed). @@ -291,7 +293,9 @@ This metric is optional. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.server.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | +| `http.server.response.size` | Histogram | `By` | Measures the size of HTTP response messages. [1] | + +**[1]:** Size as measured over the wire (compressed size if messages are compressed). @@ -447,7 +451,9 @@ This metric is optional. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | +| `http.client.request.size` | Histogram | `By` | Measures the size of HTTP request messages. [1] | + +**[1]:** Size as measured over the wire (compressed size if messages are compressed). @@ -518,7 +524,9 @@ This metric is optional. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | +| `http.client.response.size` | Histogram | `By` | Measures the size of HTTP response messages. [1] | + +**[1]:** Size as measured over the wire (compressed size if messages are compressed). diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 813179a005..34d6baaa2d 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -97,17 +97,19 @@ groups: - id: metric.http.server.request.size type: metric metric_name: http.server.request.size - brief: "Measures the size of HTTP request messages (compressed)." + brief: "Measures the size of HTTP request messages." instrument: histogram unit: "By" + note: Size as measured over the wire (compressed size if messages are compressed). extends: metric_attributes.http.server - id: metric.http.server.response.size type: metric metric_name: http.server.response.size - brief: "Measures the size of HTTP response messages (compressed)." + brief: "Measures the size of HTTP response messages." instrument: histogram unit: "By" + note: Size as measured over the wire (compressed size if messages are compressed). extends: metric_attributes.http.server - id: metric.http.client.request.duration @@ -121,15 +123,17 @@ groups: - id: metric.http.client.request.size type: metric metric_name: http.client.request.size - brief: "Measures the size of HTTP request messages (compressed)." + brief: "Measures the size of HTTP request messages." instrument: histogram unit: "By" + note: Size as measured over the wire (compressed size if messages are compressed). extends: metric_attributes.http.client - id: metric.http.client.response.size type: metric metric_name: http.client.response.size - brief: "Measures the size of HTTP response messages (compressed)." + brief: "Measures the size of HTTP response messages." instrument: histogram unit: "By" + note: Size as measured over the wire (compressed size if messages are compressed). extends: metric_attributes.http.client From 4fcf4dfd795eccec8018f628c1331b3aa1aee99d Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 30 Aug 2023 04:59:18 -0700 Subject: [PATCH 08/25] Clarify stabilization plan does not just apply to attributes (#278) --- docs/database/database-spans.md | 17 +++++++++-------- docs/http/README.md | 17 +++++++++-------- docs/http/http-metrics.md | 17 +++++++++-------- docs/http/http-spans.md | 17 +++++++++-------- docs/messaging/messaging-spans.md | 17 +++++++++-------- docs/rpc/rpc-metrics.md | 17 +++++++++-------- docs/rpc/rpc-spans.md | 17 +++++++++-------- 7 files changed, 63 insertions(+), 56 deletions(-) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 15174ac9f6..d208eebd7a 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -22,24 +22,25 @@ linkTitle: Client Calls > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Database instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in Database instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/README.md b/docs/http/README.md index e3bc209b16..a5249266f1 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -18,24 +18,25 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 26ad37b78e..e97aebdd8e 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -31,24 +31,25 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 871dc221b9..7ea7529359 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -37,24 +37,25 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> * SHOULD NOT change the version of the HTTP or networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in HTTP instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes +> * `http` - emit the new, stable HTTP and networking conventions, +> and stop emitting the old experimental HTTP and networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> * `http/dup` - emit both the old and the stable HTTP and networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental HTTP and networking attributes +> emitting whatever version of the old experimental HTTP and networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index d25a0c57b0..c1814ad8d9 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -38,24 +38,25 @@ > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/messaging.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Messaging instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in Messaging instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index d80d0c5df4..d431dd6652 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -40,24 +40,25 @@ metrics can be filtered for finer grain analysis. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index cf6a054ccc..e5bdaaf29d 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -30,24 +30,25 @@ This document defines how to describe remote procedure calls > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) > (or prior): > -> * SHOULD NOT change the version of the networking attributes that they emit +> * SHOULD NOT change the version of the networking conventions that they emit > until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). +> include stabilization of a core set of networking conventions which are also used +> in RPC instrumentations). Conventions include, but are not limited to, attributes, +> metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. > The only values defined so far are: -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes +> * `http` - emit the new, stable networking conventions, +> and stop emitting the old experimental networking conventions > that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, +> * `http/dup` - emit both the old and the stable networking conventions, > allowing for a seamless transition. > * The default behavior (in the absence of one of these values) is to continue -> emitting whatever version of the old experimental networking attributes +> emitting whatever version of the old experimental networking conventions > the instrumentation was emitting previously. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. +> for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version (stable > next major version SHOULD NOT be released prior to October 1, 2023). From 6c20838957be97f9a87c4c7467ece03499003670 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 6 Sep 2023 07:43:11 -0700 Subject: [PATCH 09/25] Update CODEOWNERS jvm paths (#301) --- .github/CODEOWNERS | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4ef9633c60..67fd007ee9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -28,8 +28,8 @@ /docs/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan # JVM semantic conventions approvers -/model/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers -/model/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/model/metrics/jvm-* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/docs/jvm/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers # HTTP semantic conventions approvers /model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers From fcad0aa62ea9d0fcf2582f003a2abf0484693619 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Thu, 7 Sep 2023 12:11:00 +0300 Subject: [PATCH 10/25] Add host cpu info (#209) Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/resource/host.md | 15 +++++++++++++ model/resource/host.yaml | 46 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6faafa19c4..ed0bba815c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,8 @@ release. ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) - Simplify HTTP metric briefs. ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) +- Add host cpu resource attributes. + ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) ## v1.21.0 (2023-07-13) diff --git a/docs/resource/host.md b/docs/resource/host.md index 96d7da4dea..150755dc19 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -31,6 +31,21 @@ | `x86` | 32-bit x86 | +**type:** `host.cpu` + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | Opt-In | +| `host.cpu.family` | int | Numeric value specifying the family or generation of the CPU. | `6` | Opt-In | +| `host.cpu.model.id` | int | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6` | Opt-In | +| `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | Opt-In | +| `host.cpu.stepping` | int | Stepping or core revisions. | `1` | Opt-In | +| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | Opt-In | + +**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. + + ## Collecting host.id from non-containerized systems ### Non-privileged Machine ID Lookup diff --git a/model/resource/host.yaml b/model/resource/host.yaml index 457aa1c8ae..2839d8f660 100644 --- a/model/resource/host.yaml +++ b/model/resource/host.yaml @@ -70,3 +70,49 @@ groups: The version string of the VM image or host OS as defined in [Version Attributes](README.md#version-attributes). examples: ['0.1'] + - id: host.cpu + prefix: host.cpu + type: resource + brief: > + A host's CPU information + attributes: + - id: vendor.id + requirement_level: opt_in + type: string + brief: > + Processor manufacturer identifier. A maximum 12-character string. + note: > + [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. + Writing these to memory in this order results in a 12-character string. + examples: [ 'GenuineIntel' ] + - id: family + requirement_level: opt_in + type: int + brief: > + Numeric value specifying the family or generation of the CPU. + examples: [ 6 ] + - id: model.id + requirement_level: opt_in + type: int + brief: > + Model identifier. It provides more granular information about the CPU, distinguishing it from + other CPUs within the same family. + examples: [ 6 ] + - id: model.name + requirement_level: opt_in + type: string + brief: > + Model designation of the processor. + examples: [ '11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz' ] + - id: stepping + requirement_level: opt_in + type: int + brief: > + Stepping or core revisions. + examples: [ 1 ] + - id: cache.l2.size + requirement_level: opt_in + type: int + brief: > + The amount of level 2 memory cache available to the processor (in Bytes). + examples: [ 12288000 ] From ff200826aec224851e754cefe1c857d4f47e36a5 Mon Sep 17 00:00:00 2001 From: Bertrand Martin <32521698+bertysentry@users.noreply.github.com> Date: Thu, 7 Sep 2023 18:58:06 +0200 Subject: [PATCH 11/25] Fix unit for hw.network.bandwidth.limit metric (#91) --- docs/system/hardware-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 7c45d8bdcf..516674d5e6 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -270,7 +270,7 @@ fiber channel port or a Wi-Fi adapter. | `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | | | | | | | `hw.type` (**Required**) | `network` | | | | | | | `direction` (Recommended) | `receive`, `transmit` | -| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | | +| `hw.network.bandwidth.limit` | Link speed | By/s | UpDownCounter | Int64 | | | | `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | | | `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | | `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | From 9e3ac90443cabde129db03d8a2a1e887f6e3fdf2 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Mon, 11 Sep 2023 12:22:44 +0300 Subject: [PATCH 12/25] Add oci.manifest.digest, container.image.repo_digests and make container.image.tag array (#159) Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/resource/container.md | 35 +++++++++++++++++++++++++++++++---- model/resource/container.yaml | 26 +++++++++++++++++++++----- model/resource/oci.yaml | 21 +++++++++++++++++++++ 4 files changed, 75 insertions(+), 9 deletions(-) create mode 100644 model/resource/oci.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index ed0bba815c..66573a09cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ release. - Update `.count` metric naming convention so that it only applies to UpDownCounters, and add that `.total` should not be used by either Counters or UpDownCounters ([#107](https://github.com/open-telemetry/semantic-conventions/pull/107)) +- Add `oci.manifest.digest`, `container.image.repo_digests` attributes. Make `container.image.tag` array and in plural form. + ([#159](https://github.com/open-telemetry/semantic-conventions/pull/159)) - BREAKING: Rename `http.client.duration` and `http.server.duration` metrics to `http.client.request.duration` and `http.server.request.duration` respectively. ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) diff --git a/docs/resource/container.md b/docs/resource/container.md index 264a7d53bc..b0017c4b36 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -13,17 +13,44 @@ | `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended | | `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | | `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | -| `container.image.tag` | string | Container image tag. | `0.1` | Recommended | +| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | | `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [1] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | -| `container.command` | string | The command used to run the container (i.e. the command name). [2] | `otelcontribcol` | Opt-In | +| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [2] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | +| `container.command` | string | The command used to run the container (i.e. the command name). [3] | `otelcontribcol` | Opt-In | | `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | | `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | **[1]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. -OCI defines a digest of manifest. +The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. -**[2]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. +**[2]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. + +**[3]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + + +## Open Container Initiative (OCI) + +The [Open Container Initiative](https://opencontainers.org/) defines open industry standards around container formats and runtimes. + +### OCI Image Manifest + +This section refers to the [specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md) +that defines an OCI Image manifest. + +**Status**: [Experimental][DocumentStatus] + +**type:** `oci` + +**Description:** Attributes of an OCI image manifest. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | Recommended | + +**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/resource/container.yaml b/model/resource/container.yaml index f3f52c7cfa..3dbac9641b 100644 --- a/model/resource/container.yaml +++ b/model/resource/container.yaml @@ -27,11 +27,14 @@ groups: brief: > Name of the image the container was built on. examples: ['gcr.io/opentelemetry/operator'] - - id: image.tag - type: string + - id: image.tags + type: string[] brief: > - Container image tag. - examples: ['0.1'] + Container image tags. An example can be found in + [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). + Should be only the `` section of the full name for example + from `registry.example.com/my-org/my-image:`. + examples: ['v1.27.1', '3.5.7-0'] - id: image.id type: string brief: > @@ -44,8 +47,21 @@ groups: K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. - OCI defines a digest of manifest. + The ID is assinged by the container runtime and can vary in different environments. + Consider using `oci.manifest.digest` if it is important to identify the same + image in different environments/runtimes. examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] + - id: image.repo_digests + type: string[] + brief: > + Repo digests of the container image as provided by the container runtime. + note: > + [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and + [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) + report those under the `RepoDigests` field. + examples: + - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' + - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' - id: command type: string requirement_level: opt_in diff --git a/model/resource/oci.yaml b/model/resource/oci.yaml new file mode 100644 index 0000000000..fc1ff2ebb3 --- /dev/null +++ b/model/resource/oci.yaml @@ -0,0 +1,21 @@ +groups: + - id: oci.manifest + prefix: oci.manifest + type: resource + brief: > + An OCI image manifest. + attributes: + - id: digest + type: string + brief: > + The digest of the OCI image manifest. For container images specifically is the + digest by which the container image is known. + note: > + Follows + [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), + and specifically the + [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). + + An example can be found in + [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). + examples: [ 'sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4' ] From 58b08c9dfbe4516b8ba8bdd73c403dd3c3931d69 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Mon, 11 Sep 2023 10:30:14 +0100 Subject: [PATCH 13/25] Add `cluster.name` and `node.name` attributes to Elasticsearch semantic conventions. (#285) Co-authored-by: Alexander Wert Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/database/elasticsearch.md | 42 +++++++++++++++++++++------------- model/trace/database.yaml | 19 +++++++++++++++ 3 files changed, 47 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66573a09cd..3fbe4268e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ release. ## Unreleased +- Add `cluster.name` and `node.name` attributes to Elasticsearch semantic conventions. + ([#285](https://github.com/open-telemetry/semantic-conventions/pull/285)) - Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) - Update `.count` metric naming convention so that it only applies to UpDownCounters, diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index ae329f7e5e..43003ddc8b 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -6,7 +6,11 @@ linkTitle: Elasticsearch **Status**: [Experimental][DocumentStatus] -This document defines semantic conventions to apply when creating a span for requests to Elasticsearch. +The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md) +that describe common database operations attributes in addition to the Semantic Conventions +described on this page. + +`db.system` MUST be set to `"elasticsearch"`. ## Span Name @@ -30,25 +34,29 @@ in order to map the path part values to their names. **[1]:** when the url has dynamic values -## Span attributes - -`db.system` MUST be set to `"elasticsearch"`. +## Call-level attributes | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required | -| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] | -| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com` | See below | -| [`server.port`](../general/attributes.md) | int | Server port number [5] | `80`; `8080`; `443` | Recommended | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | Recommended: [2] | +| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [3] | `search`; `ml.close_job`; `cat.aliases` | Required | +| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [4] | +| `http.request.method` | string | HTTP request method. [5] | `GET`; `POST`; `HEAD` | Required | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [6] | `example.com` | See below | +| [`server.port`](../general/attributes.md) | int | Server port number [7] | `80`; `8080`; `443` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [8] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | + +**[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + +**[2]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. -**[1]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. +**[3]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -**[2]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. +**[4]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[5]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -63,12 +71,12 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[6]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. +**[8]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. @@ -86,5 +94,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | `db.operation` | `"search"` | | `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` | | `db.elasticsearch.path_parts.index` | `"my-index-000001"` | +| `db.elasticsearch.cluster.name` | `"e9106fc68e3044f0b1475b04bf4ffd5f"` | +| `db.elasticsearch.node.name` | `"instance-0000000001"` | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 73f6005d08..2348a2a0f0 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -413,6 +413,7 @@ groups: note: > For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. + - id: db.mongodb prefix: db.mongodb type: span @@ -453,6 +454,24 @@ groups: examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] - ref: server.address - ref: server.port + - id: cluster.name + type: string + requirement_level: + recommended: > + When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. + tag: call-level-tech-specific + brief: > + Represents the identifier of an Elasticsearch cluster. + examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] + - id: node.name + type: string + requirement_level: + recommended: > + When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. + tag: call-level-tech-specific + brief: > + Represents the human-readable identifier of the node/instance to which a request was routed. + examples: ["instance-0000000001"] - id: db.sql prefix: 'db.sql' From d7930d3ca56dd7f0ee2de56aaefe539421a74ab5 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 11 Sep 2023 06:37:44 -0700 Subject: [PATCH 14/25] Move RPC streaming notes from metric brief section to notes section (#275) Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 + docs/rpc/rpc-metrics.md | 48 +++++++++++++++++++----- model/metrics/rpc-metrics.yaml | 68 +++++++++++++++++++--------------- 3 files changed, 78 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fbe4268e9..f5bb6bd12a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,8 @@ release. ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) - Add host cpu resource attributes. ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) +- Moved RPC streaming notes from metric brief section to notes section. + ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275)) ## v1.21.0 (2023-07-13) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index d431dd6652..d51e609be6 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -80,10 +80,12 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. **Streaming**: N/A. [1] | +| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. [1] | **[1]:** While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. + +**Streaming**: N/A. #### Metric: `rpc.server.request.size` @@ -93,7 +95,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch | +| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | + +**[1]:** **Streaming**: Recorded per message in a streaming batch #### Metric: `rpc.server.response.size` @@ -103,7 +107,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch | +| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | + +**[1]:** **Streaming**: Recorded per response in a streaming batch #### Metric: `rpc.server.requests_per_rpc` @@ -113,7 +119,11 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | +| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming** : This metric is required for server and client streaming RPCs #### Metric: `rpc.server.responses_per_rpc` @@ -123,7 +133,11 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | +| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs ### RPC Client @@ -138,10 +152,12 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC **Streaming**: N/A. [1] | +| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC. [1] | **[1]:** While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. + +**Streaming**: N/A. #### Metric: `rpc.client.request.size` @@ -151,7 +167,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch | +| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | + +**[1]:** **Streaming**: Recorded per message in a streaming batch #### Metric: `rpc.client.response.size` @@ -161,7 +179,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch | +| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | + +**[1]:** **Streaming**: Recorded per response in a streaming batch #### Metric: `rpc.client.requests_per_rpc` @@ -171,7 +191,11 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | +| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs #### Metric: `rpc.client.responses_per_rpc` @@ -181,7 +205,11 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | +| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] | + +**[1]:** Should be 1 for all non-streaming RPCs. + +**Streaming**: This metric is required for server and client streaming RPCs ## Attributes diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml index 38755d4bf2..237107e6d8 100644 --- a/model/metrics/rpc-metrics.yaml +++ b/model/metrics/rpc-metrics.yaml @@ -20,96 +20,104 @@ groups: - id: metric.rpc.server.duration type: metric metric_name: rpc.server.duration - brief: > - Measures the duration of inbound RPC. - **Streaming**: N/A. + brief: Measures the duration of inbound RPC. instrument: histogram unit: "ms" note: | While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. + **Streaming**: N/A. + - id: metric.rpc.server.request.size type: metric metric_name: rpc.server.request.size - brief: > - Measures the size of RPC request messages (uncompressed). - **Streaming**: Recorded per message in a streaming batch + brief: Measures the size of RPC request messages (uncompressed). instrument: histogram unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch - id: metric.rpc.server.response.size type: metric metric_name: rpc.server.response.size - brief: > - Measures the size of RPC response messages (uncompressed). - **Streaming**: Recorded per response in a streaming batch + brief: Measures the size of RPC response messages (uncompressed). instrument: histogram unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch - id: metric.rpc.server.requests_per_rpc type: metric metric_name: rpc.server.requests_per_rpc - brief: > - Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs + brief: Measures the number of messages received per RPC. instrument: histogram unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming** : This metric is required for server and client streaming RPCs - id: metric.rpc.server.responses_per_rpc type: metric metric_name: rpc.server.responses_per_rpc - brief: > - Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs + brief: Measures the number of messages sent per RPC. instrument: histogram unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs # RPC Client metrics - id: metric.rpc.client.duration type: metric metric_name: rpc.client.duration - brief: > - Measures the duration of outbound RPC - **Streaming**: N/A. + brief: Measures the duration of outbound RPC. instrument: histogram unit: "ms" note: | While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. + **Streaming**: N/A. + - id: metric.rpc.client.request.size type: metric metric_name: rpc.client.request.size - brief: > - Measures the size of RPC request messages (uncompressed). - **Streaming**: Recorded per message in a streaming batch + brief: Measures the size of RPC request messages (uncompressed). instrument: histogram unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch - id: metric.rpc.client.response.size type: metric metric_name: rpc.client.response.size - brief: > - Measures the size of RPC response messages (uncompressed). - **Streaming**: Recorded per response in a streaming batch + brief: Measures the size of RPC response messages (uncompressed). instrument: histogram unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch - id: metric.rpc.client.requests_per_rpc type: metric metric_name: rpc.client.requests_per_rpc - brief: > - Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs + brief: Measures the number of messages received per RPC. instrument: histogram unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs - id: metric.rpc.client.responses_per_rpc type: metric metric_name: rpc.client.responses_per_rpc - brief: > - Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. - **Streaming**: This metric is required for server and client streaming RPCs + brief: Measures the number of messages sent per RPC. instrument: histogram unit: "{count}" + note: | + Should be 1 for all non-streaming RPCs. + + **Streaming**: This metric is required for server and client streaming RPCs From 3e16365a273b325aa0dff1160a6d89bc15900124 Mon Sep 17 00:00:00 2001 From: Karming <41309630+karmingc@users.noreply.github.com> Date: Mon, 11 Sep 2023 09:48:34 -0400 Subject: [PATCH 15/25] chore: fix doc reference to docs (#305) Co-authored-by: Joao Grassi Co-authored-by: Josh Suereth --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b8b2cf6f6..e1c1b8dbb9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This repository is currently using [this specification version][SpecificationVer ## Read the docs -The documentation currently resides in the [doc](docs/README.md) folder. +The documentation currently resides in the [docs](docs/README.md) folder. ## Contributing From 5f6558d259cc10b5f151e4d1230fea3ad24abb41 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 11 Sep 2023 08:19:57 -0700 Subject: [PATCH 16/25] Use `HTTP` instead of `_OTHER` in HTTP span names (if method is unknown) (#270) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Trask Stalnaker Co-authored-by: Joao Grassi Co-authored-by: Christian Neumüller Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 ++ docs/http/http-spans.md | 22 ++++++++++++++++------ package.json | 2 +- 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5bb6bd12a..07f5034aed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,8 @@ release. ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) - Add host cpu resource attributes. ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) +- BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`) + ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) - Moved RPC streaming notes from metric brief section to notes section. ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275)) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 7ea7529359..b5d828c9e6 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -62,13 +62,23 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a -(low-cardinality) `http.route` available. -HTTP server span names SHOULD be `{http.request.method}` if there is no (low-cardinality) -`http.route` available. + + + +HTTP server span names SHOULD be `{method} {http.route}` if there is a +(low-cardinality) `http.route` available (see below for the exact definition of the [`{method}`](#method-placeholder) placeholder). + +If there is no (low-cardinality) `http.route` available, HTTP server span names +SHOULD be [`{method}`](#method-placeholder). + HTTP client spans have no `http.route` attribute since client-side instrumentation -is not generally aware of the "route", and therefore HTTP client spans SHOULD use -`{http.request.method}`. +is not generally aware of the "route", and therefore HTTP client spans SHOULD be +[`{method}`](#method-placeholder). + + +The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. +In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` MUST be `HTTP`. + Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the default span name. diff --git a/package.json b/package.json index d51304272a..90d26767c2 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "devDependencies": { "gulp": "^4.0.2", "js-yaml": "^4.1.0", - "markdown-link-check": "3.10.3", + "markdown-link-check": "^3.11.2", "markdown-toc": "^1.2.0", "markdownlint": "^0.29.0", "markdownlint-cli": "0.31.0", From 2bad9afad58fbd6b33cc683d1ad1f006e35e4a5d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 11 Sep 2023 08:37:09 -0700 Subject: [PATCH 17/25] Introduce request error type attribute (#205) Co-authored-by: Joao Grassi Co-authored-by: Trask Stalnaker Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 + docs/http/http-metrics.md | 252 +++++++++++++++++++++++++++++--------- docs/http/http-spans.md | 86 +++++++++++-- model/error.yaml | 31 +++++ model/http-common.yaml | 20 +++ model/metrics/http.yaml | 40 ++++++ 6 files changed, 367 insertions(+), 64 deletions(-) create mode 100644 model/error.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 07f5034aed..5e438617ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,8 @@ release. ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) - Add host cpu resource attributes. ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) +- Introduce `error.type` attribute and use it in HTTP conventions + ([#205](https://github.com/open-telemetry/semantic-conventions/pull/205)) - BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`) ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) - Moved RPC streaming notes from metric brief section to notes section. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index e97aebdd8e..07c065f2ab 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -77,18 +77,35 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -103,9 +120,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -115,13 +132,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[5]:** Determined by using the first of the following that applies +**[6]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -224,18 +247,35 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -250,9 +290,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -262,13 +302,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[5]:** Determined by using the first of the following that applies +**[6]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -303,18 +349,35 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -329,9 +392,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -341,13 +404,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[5]:** Determined by using the first of the following that applies +**[6]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -387,15 +456,32 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -410,9 +496,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies +**[4]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -420,13 +506,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -460,15 +552,32 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -483,9 +592,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies +**[4]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -493,13 +602,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -533,15 +648,32 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -556,9 +688,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies +**[4]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -566,13 +698,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index b5d828c9e6..2fa3121bb9 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -29,6 +29,9 @@ and various HTTP versions like 1.1, 2 and SPDY. * [HTTP client retries examples](#http-client-retries-examples) * [HTTP client authorization retry examples](#http-client-authorization-retry-examples) * [HTTP client redirects examples](#http-client-redirects-examples) + * [HTTP client call: DNS error](#http-client-call-dns-error) + * [HTTP client call: Internal Server Error](#http-client-call-internal-server-error) + * [HTTP server call: connection dropped before response body was sent](#http-server-call-connection-dropped-before-response-body-was-sent) @@ -98,6 +101,12 @@ failed to interpret, span status MUST be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. +HTTP request may fail if it was cancelled or an error occurred preventing +the client or server from sending/receiving the request/response fully. + +When instrumentation detects such errors it MUST set span status to `Error` +and MUST set the `error.type` attribute. + ## Common Attributes The common attributes listed in this section apply to both HTTP clients and servers in addition to @@ -111,16 +120,33 @@ sections below. | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | | `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [5] | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | 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` | Recommended | **[1]:** If and only if it's different than `http.request.method`. -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** If the request fails with an error before response status code was sent or received, +`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + +If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -135,14 +161,20 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[4]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[5]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * `http.request.method` +`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. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `http.request.method` 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 | @@ -422,7 +454,7 @@ Span name: `GET` | Attribute name | Value | | :------------------- | :-------------------------------------------------------| | `http.request.method`| `"GET"` | -| `network.protocol.version` | `"1.1"` | +| `network.protocol.version` | `"1.1"` | | `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` | | `server.address` | `example.com` | | `server.port` | 8080 | @@ -540,4 +572,44 @@ GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) --- server (SERVER, trace=t2, span=s2) ``` +### HTTP client call: DNS error + +As an example, if a user requested `https://does-not-exist-123.com`, we may have the following span on the client side: + +| Attribute name | Value | +| :------------------- | :-------------------------------------------------------| +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://does-not-exist-123.com"` | +| `server.address` | `"does-not-exist-123.com"` | +| `error.type` | `"java.net.UnknownHostException"` | + +### HTTP client call: Internal Server Error + +As an example, if a user requested `https://example.com` and server returned 500, we may have the following span on the client side: + +| Attribute name | Value | +| :------------------- | :-------------------------------------------------------| +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://example.com"` | +| `server.address` | `"example.com"` | +| `http.response.status_code` | `500` | +| `error.type` | `"500"` | + +### HTTP server call: connection dropped before response body was sent + +As an example, if a user sent a `POST` request with a body to `https://example.com:8080/uploads/4`, we may see the following span on a server side: + +Span name: `POST /uploads/:document_id`. + +| Attribute name | Value | +| :------------------- | :---------------------------------------------- | +| `http.request.method`| `"GET"` | +| `url.path` | `"/uploads/4"` | +| `url.scheme` | `"https"` | +| `http.route` | `"/uploads/:document_id"` | +| `http.response.status_code` | `201` | +| `error.type` | `WebSocketDisconnect` | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/error.yaml b/model/error.yaml new file mode 100644 index 0000000000..cdfc587800 --- /dev/null +++ b/model/error.yaml @@ -0,0 +1,31 @@ +groups: + - id: error + type: attribute_group + prefix: error + brief: > + This document defines the shared attributes used to + report an error. + attributes: + - id: type + brief: 'Describes a class of error the operation ended with.' + type: + allow_custom_values: true + members: + - id: other + value: "_OTHER" + brief: 'A fallback error value to be used when the instrumentation does not define a custom value for it.' + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] + note: | + The `error.type` SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + + If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + + If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), + it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture + all errors, regardless of whether they are defined within the domain-specific set or not. diff --git a/model/http-common.yaml b/model/http-common.yaml index 2b481800e1..b6643676db 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -62,6 +62,26 @@ groups: conditionally_required: If and only if one was received/sent. brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' examples: [200] + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'name_resolution_error', '500'] + note: | + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + + If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. - ref: network.protocol.name examples: ['http', 'spdy'] requirement_level: diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 34d6baaa2d..f6354aa7d5 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -31,6 +31,26 @@ groups: if it's sent in absolute-form. - Port identifier of the `Host` header # todo (lmolkova) build tools don't populate grandparent attributes + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'name_resolution_error', '500'] + note: | + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + + If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. - ref: http.request.method - ref: http.response.status_code - ref: network.protocol.name @@ -47,6 +67,26 @@ groups: - ref: network.protocol.name - ref: network.protocol.version - ref: server.socket.address + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'name_resolution_error', '500'] + note: | + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. + + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + + If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. - id: metric.http.server.request.duration type: metric From db3a9aaf669aded5696a26f57c74703a97e6f3c6 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 11 Sep 2023 20:34:49 +0200 Subject: [PATCH 18/25] [.github/CODEOWNERS] Add semconv system approvers (#309) Co-authored-by: Reiley Yang --- .github/CODEOWNERS | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 67fd007ee9..0c016ce011 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -35,4 +35,10 @@ /model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/trace/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +# System semantic conventions approvers +/docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/metrics/system-* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/docs/resource/host.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/resource/host.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers + # TODO - Add semconv area experts From d80c8e317ff8709cb6dc85dc6cd9472f153e81dc Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 12 Sep 2023 16:54:28 +0200 Subject: [PATCH 19/25] BREAKING: Generate System metrics semconv from YAML + move attributes to their own namespace (#89) Co-authored-by: Armin Ruech Co-authored-by: Pablo Baeyens --- CHANGELOG.md | 27 + docs/system/system-metrics.md | 840 ++++++++++++++++++++++++------ model/metrics/system-metrics.yaml | 492 +++++++++++++++++ schema-next.yaml | 64 +++ 4 files changed, 1277 insertions(+), 146 deletions(-) create mode 100644 model/metrics/system-metrics.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e438617ba..4612cb77e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,33 @@ release. ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) - Moved RPC streaming notes from metric brief section to notes section. ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275)) +- BREAKING: Generate System metrics semconv from YAML. + ([#89](https://github.com/open-telemetry/semantic-conventions/pull/89)) + - Rename attributes for `system.cpu.*` metrics: + - `state` to `system.cpu.state` + - `cpu` to `system.cpu.logical_number` + - Rename attributes for `system.memory.*` metrics: + - `state` to `system.memory.state` + - Rename attributes for `system.paging.*` metrics: + - `state` to `system.paging.state` + - `type` to `system.paging.type` + - `direction` to `system.paging.direction` + - Rename attributes for `system.disk.*` metrics: + - `device` to `system.device` + - `direction` to `system.disk.direction` + - Rename attributes for `system.filesystem.*` metrics: + - `device` to `system.device` + - `state` to `system.filesystem.state` + - `type` to `system.filesystem.type` + - `mode` to `system.filesystem.mode` + - `mountpoint` to `system.filesystem.mountpoint` + - Rename attributes for `system.network.*` metrics: + - `device` to `system.device` + - `direction` to `system.network.direction` + - `protocol` to `network.protocol` + - `state` to `system.network.state` + - Rename attributes for `system.processes.*` metrics: + - `status` to `system.processes.status` ## v1.21.0 (2023-07-13) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 2f71ef86af..f17b799050 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -15,154 +15,701 @@ instruments not explicitly defined in the specification. -- [Metric Instruments](#metric-instruments) - * [`system.cpu.` - Processor metrics](#systemcpu---processor-metrics) - * [`system.memory.` - Memory metrics](#systemmemory---memory-metrics) - * [`system.paging.` - Paging/swap metrics](#systempaging---pagingswap-metrics) - * [`system.disk.` - Disk controller metrics](#systemdisk---disk-controller-metrics) - * [`system.filesystem.` - Filesystem metrics](#systemfilesystem---filesystem-metrics) - * [`system.network.` - Network metrics](#systemnetwork---network-metrics) - * [`system.processes.` - Aggregate system process metrics](#systemprocesses---aggregate-system-process-metrics) - * [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) +- [Processor Metrics](#processor-metrics) + * [Metric: `system.cpu.time`](#metric-systemcputime) + * [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) + * [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount) + * [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount) +- [Memory Metrics](#memory-metrics) + * [Metric: `system.memory.usage`](#metric-systemmemoryusage) + * [Metric: `system.memory.utilization`](#metric-systemmemoryutilization) +- [Paging/Swap Metrics](#pagingswap-metrics) + * [Metric: `system.paging.usage`](#metric-systempagingusage) + * [Metric: `system.paging.utilization`](#metric-systempagingutilization) + * [Metric: `system.paging.faults`](#metric-systempagingfaults) + * [Metric: `system.paging.operations`](#metric-systempagingoperations) +- [Disk Controller Metrics](#disk-controller-metrics) + * [Metric: `system.disk.io`](#metric-systemdiskio) + * [Metric: `system.disk.operations`](#metric-systemdiskoperations) + * [Metric: `system.disk.io_time`](#metric-systemdiskio_time) + * [Metric: `system.disk.operation_time`](#metric-systemdiskoperation_time) + * [Metric: `system.disk.merged`](#metric-systemdiskmerged) +- [Filesystem Metrics](#filesystem-metrics) + * [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage) + * [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization) +- [Network Metrics](#network-metrics) + * [Metric: `system.network.dropped`](#metric-systemnetworkdropped) + * [Metric: `system.network.packets`](#metric-systemnetworkpackets) + * [Metric: `system.network.errors`](#metric-systemnetworkerrors) + * [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) +- [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) -## Metric Instruments - -### `system.cpu.` - Processor metrics - -**Description:** System level processor metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | -| system.cpu.time | Seconds each logical CPU spent on each mode | s | Counter | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | Logical CPU number [0..n-1] | -| system.cpu.utilization | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | Logical CPU number (0..n) | -| system.cpu.physical.count | Reports the number of actual physical processor cores on the hardware | {cpu} | UpDownCounter | Int64 | | | -| system.cpu.logical.count | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking | {cpu} | UpDownCounter | Int64 | | | - -### `system.memory.` - Memory metrics - -**Description:** System level memory metrics. This does not include [paging/swap -memory](#systempaging---pagingswap-metrics). - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ | -| system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. | -| system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. | - -### `system.paging.` - Paging/swap metrics - -**Description:** System level paging/swap memory metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free | -| system.paging.utilization | | 1 | Gauge | Double | state | used, free | -| system.paging.faults | | {fault} | Counter | Int64 | type | major, minor | -| system.paging.operations | | {operation} | Counter | Int64 | type | major, minor | -| | | | | | direction | in, out | - -### `system.disk.` - Disk controller metrics - -**Description:** System level disk performance metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.disk.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.operations | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.io_time\[1\] | Time disk spent activated | s | Counter | Double | device | (identifier) | -| system.disk.operation_time\[2\] | Sum of the time each operation took to complete | s | Counter | Double | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.merged | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | - -1 The real elapsed time ("wall clock") -used in the I/O path (time from operations running in parallel are not -counted). Measured as: - -- Linux: Field 13 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: The complement of ["Disk\% Idle -Time"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).) -performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` - -2 Because it is the sum of time each -request took, parallel-issued requests each contribute to make the count -grow. Measured as: - -- Linux: Fields 7 & 11 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" -perf counter (similar for Writes) - -### `system.filesystem.` - Filesystem metrics - -**Description:** System level filesystem metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- | -| system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | -| system.filesystem.utilization | | 1 | Gauge | Double | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | - -### `system.network.` - Network metrics - -**Description:** System level network metrics. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.packets | | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.errors\[2\] | Count of network errors detected | {error} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.connections | | {connection} | UpDownCounter | Int64 | device | (identifier) | -| | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | -| | | | | | state | If specified, SHOULD be one of: close, close_wait, closing, delete, established, fin_wait_1, fin_wait_2, last_ack, listen, syn_recv, syn_sent, time_wait. A stateless protocol MUST NOT set this attribute. | - -1 Measured as: - -- Linux: the `drop` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InDiscards`/`OutDiscards`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -2 Measured as: - -- Linux: the `errs` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InErrors`/`OutErrors`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -### `system.processes.` - Aggregate system process metrics - -**Description:** System level aggregate process metrics. For metrics at the -individual process level, see [process metrics](process-metrics.md). - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | -| system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - | - -### `system.{os}.` - OS Specific System Metrics +## Processor Metrics + +**Description:** System level processor metrics captured under the namespace `system.cpu`. + +### Metric: `system.cpu.time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.cpu.time` | Counter | `s` | Seconds each logical CPU spent on each mode | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | Recommended | +| `system.cpu.state` | string | The state of the CPU | `idle`; `interrupt` | Recommended | + +`system.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 | +|---|---| +| `user` | user | +| `system` | system | +| `nice` | nice | +| `idle` | idle | +| `iowait` | iowait | +| `interrupt` | interrupt | +| `steal` | steal | + + +### Metric: `system.cpu.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.cpu.utilization` | Gauge | `1` | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | Recommended | +| `system.cpu.state` | string | The state of the CPU | `idle`; `interrupt` | Recommended | + +`system.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 | +|---|---| +| `user` | user | +| `system` | system | +| `nice` | nice | +| `idle` | idle | +| `iowait` | iowait | +| `interrupt` | interrupt | +| `steal` | steal | + + +### Metric: `system.cpu.physical.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.cpu.physical.count` | UpDownCounter | `{cpu}` | Reports the number of actual physical processor cores on the hardware | + + + + + +### Metric: `system.cpu.logical.count` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.cpu.logical.count` | UpDownCounter | `{cpu}` | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking | + + + + + +## Memory Metrics + +**Description:** System level memory metrics capture under the namespace `system.memory`. +This does not include [paging/swap memory](#pagingswap-metrics). + +### Metric: `system.memory.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.memory.usage` | UpDownCounter | `By` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.memory.state` | string | The memory state | `free`; `cached` | Recommended | + +`system.memory.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 | +|---|---| +| `total` | total | +| `used` | used | +| `free` | free | +| `shared` | shared | +| `buffers` | buffers | +| `cached` | cached | + + +### Metric: `system.memory.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.memory.utilization` | Gauge | `1` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.memory.state` | string | The memory state | `free`; `cached` | Recommended | + +`system.memory.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 | +|---|---| +| `total` | total | +| `used` | used | +| `free` | free | +| `shared` | shared | +| `buffers` | buffers | +| `cached` | cached | + + +## Paging/Swap Metrics + +**Description:** System level paging/swap memory metrics captured under the namespace `system.paging`. + +### Metric: `system.paging.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.paging.usage` | UpDownCounter | `By` | Unix swap or windows pagefile usage | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.paging.state` | string | The memory paging state | `free` | Recommended | + +`system.paging.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `used` | used | +| `free` | free | + + +### Metric: `system.paging.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.paging.utilization` | Gauge | `1` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.paging.state` | string | The memory paging state | `free` | Recommended | + +`system.paging.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `used` | used | +| `free` | free | + + +### Metric: `system.paging.faults` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.paging.faults` | Counter | `{fault}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.paging.type` | string | The memory paging type | `minor` | Recommended | + +`system.paging.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `major` | major | +| `minor` | minor | + + +### Metric: `system.paging.operations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.paging.operations` | Counter | `{operation}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.paging.direction` | string | The paging access direction | `in` | Recommended | +| `system.paging.type` | string | The memory paging type | `minor` | Recommended | + +`system.paging.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `in` | in | +| `out` | out | + +`system.paging.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `major` | major | +| `minor` | minor | + + +## Disk Controller Metrics + +**Description:** System level disk performance metrics captured under the namespace `system.disk`. + +### Metric: `system.disk.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.disk.io` | Counter | `By` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | + +`system.disk.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `system.disk.operations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.disk.operations` | Counter | `{operation}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | + +`system.disk.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `system.disk.io_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.disk.io_time` | Counter | `s` | Time disk spent activated [1] | + +**[1]:** The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: + +- Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: The complement of + ["Disk\% Idle Time"](https://learn.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | + + +### Metric: `system.disk.operation_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.disk.operation_time` | Counter | `s` | Sum of the time each operation took to complete [1] | + +**[1]:** Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: + +- Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) +- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes) + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | + +`system.disk.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `system.disk.merged` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.disk.merged` | Counter | `{operation}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | + +`system.disk.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + + +## Filesystem Metrics + +**Description:** System level filesystem metrics captured under the namespace `system.filesystem`. + +### Metric: `system.filesystem.usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.filesystem.usage` | UpDownCounter | `By` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.filesystem.mode` | string | The filesystem mode | `rw, ro` | Recommended | +| `system.filesystem.mountpoint` | string | The filesystem mount path | `/mnt/data` | Recommended | +| `system.filesystem.state` | string | The filesystem state | `used` | Recommended | +| `system.filesystem.type` | string | The filesystem type | `ext4` | Recommended | + +`system.filesystem.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `used` | used | +| `free` | free | +| `reserved` | reserved | + +`system.filesystem.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 | +|---|---| +| `fat32` | fat32 | +| `exfat` | exfat | +| `ntfs` | ntfs | +| `refs` | refs | +| `hfsplus` | hfsplus | +| `ext4` | ext4 | + + +### Metric: `system.filesystem.utilization` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.filesystem.utilization` | Gauge | `1` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.filesystem.mode` | string | The filesystem mode | `rw, ro` | Recommended | +| `system.filesystem.mountpoint` | string | The filesystem mount path | `/mnt/data` | Recommended | +| `system.filesystem.state` | string | The filesystem state | `used` | Recommended | +| `system.filesystem.type` | string | The filesystem type | `ext4` | Recommended | + +`system.filesystem.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `used` | used | +| `free` | free | +| `reserved` | reserved | + +`system.filesystem.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 | +|---|---| +| `fat32` | fat32 | +| `exfat` | exfat | +| `ntfs` | ntfs | +| `refs` | refs | +| `hfsplus` | hfsplus | +| `ext4` | ext4 | + + +## Network Metrics + +**Description:** System level network metrics captured under the namespace `system.network`. + +### Metric: `system.network.dropped` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.network.dropped` | Counter | `{packet}` | Count of packets that are dropped or discarded even though there was no error [1] | + +**[1]:** Measured as: + +- Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) +- Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2) + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.network.direction` | string | | `transmit` | Recommended | + +`system.network.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + + +### Metric: `system.network.packets` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.network.packets` | Counter | `{packet}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.network.direction` | string | | `transmit` | Recommended | + +`system.network.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + + +### Metric: `system.network.errors` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.network.errors` | Counter | `{error}` | Count of network errors detected [1] | + +**[1]:** Measured as: + +- Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). +- Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.network.direction` | string | | `transmit` | Recommended | + +`system.network.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + + +### Metric: `system.network.io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.network.io` | Counter | `By` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.network.direction` | string | | `transmit` | Recommended | + +`system.network.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + + +### Metric: `system.network.connections` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.network.connections` | UpDownCounter | `{connection}` | | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| `system.device` | string | The device identifier | `(identifier)` | Recommended | +| `system.network.state` | string | A stateless protocol MUST NOT set this attribute | `close_wait` | Recommended | + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`system.network.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `close` | close | +| `close_wait` | close_wait | +| `closing` | closing | +| `delete` | delete | +| `established` | established | +| `fin_wait_1` | fin_wait_1 | +| `fin_wait_2` | fin_wait_2 | +| `last_ack` | last_ack | +| `listen` | listen | +| `syn_recv` | syn_recv | +| `syn_sent` | syn_sent | +| `time_wait` | time_wait | + +## Aggregate System Process Metrics + +**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` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.processes.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.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. + +| Value | Description | +|---|---| +| `running` | running | +| `sleeping` | sleeping | +| `stopped` | stopped | +| `defunct` | defunct | + + +### Metric: `system.processes.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.{os}.` - OS Specific System Metrics Instrument names for system level metrics that have different and conflicting meaning across multiple OSes should be prefixed with `system.{os}.` and @@ -190,4 +737,5 @@ An instrument for load average over 1 minute on Linux could be named `system.linux.cpu.load_1m`, reusing the `cpu` name proposed above and having an `{os}` prefix to split this metric across OSes. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml new file mode 100644 index 0000000000..41c508f3d2 --- /dev/null +++ b/model/metrics/system-metrics.yaml @@ -0,0 +1,492 @@ +groups: + # General system attributes + - id: attributes.system + prefix: system + type: attribute_group + brief: "Describes System metric attributes" + attributes: + - id: device + type: string + brief: "The device identifier" + examples: ["(identifier)"] + + # system.cpu.* metrics and attribute group + - id: attributes.system.cpu + prefix: system.cpu + type: attribute_group + brief: "Describes System CPU metric attributes" + attributes: + - id: state + type: + allow_custom_values: true + members: + - id: user + value: 'user' + - id: system + value: 'system' + - id: nice + value: 'nice' + - id: idle + value: 'idle' + - id: iowait + value: 'iowait' + - id: interrupt + value: 'interrupt' + - id: steal + value: 'steal' + brief: "The state of the CPU" + examples: ["idle", "interrupt"] + - id: logical_number + type: int + brief: "The logical CPU number [0..n-1]" + examples: [1] + + - id: metric.system.cpu.time + type: metric + metric_name: system.cpu.time + brief: "Seconds each logical CPU spent on each mode" + instrument: counter + unit: "s" + attributes: + - ref: system.cpu.state + - ref: system.cpu.logical_number + + - id: metric.system.cpu.utilization + type: metric + metric_name: system.cpu.utilization + brief: "Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs" + instrument: gauge + unit: "1" + attributes: + - ref: system.cpu.state + - ref: system.cpu.logical_number + + - id: metric.system.cpu.physical.count + type: metric + metric_name: system.cpu.physical.count + brief: "Reports the number of actual physical processor cores on the hardware" + instrument: updowncounter + unit: "{cpu}" + attributes: [] + + - id: metric.system.cpu.logical.count + type: metric + metric_name: system.cpu.logical.count + brief: "Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking" + instrument: updowncounter + unit: "{cpu}" + attributes: [] + + # sytem.memory.* metrics and attribute group + - id: attributes.system.memory + prefix: system.memory + type: attribute_group + brief: "Describes System Memory metric attributes" + attributes: + - id: state + type: + allow_custom_values: true + members: + - id: total + value: 'total' + - id: used + value: 'used' + - id: free + value: 'free' + - id: shared + value: 'shared' + - id: buffers + value: 'buffers' + - id: cached + value: 'cached' + brief: "The memory state" + examples: ["free", "cached"] + + - id: metric.system.memory.usage + type: metric + metric_name: system.memory.usage + brief: "" + instrument: updowncounter + unit: "By" + attributes: + - ref: system.memory.state + + - id: metric.system.memory.utilization + type: metric + metric_name: system.memory.utilization + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.memory.state + + # system.paging.* metrics and attribute group + - id: attributes.system.paging + prefix: system.paging + type: attribute_group + brief: "Describes System Memory Paging metric attributes" + attributes: + - id: state + type: + allow_custom_values: false + members: + - id: used + value: 'used' + - id: free + value: 'free' + brief: "The memory paging state" + examples: ["free"] + - id: type + type: + allow_custom_values: false + members: + - id: major + value: 'major' + - id: minor + value: 'minor' + brief: "The memory paging type" + examples: ["minor"] + - id: direction + type: + allow_custom_values: false + members: + - id: in + value: 'in' + - id: out + value: 'out' + brief: "The paging access direction" + examples: ["in"] + - id: metric.system.paging.usage + type: metric + metric_name: system.paging.usage + brief: "Unix swap or windows pagefile usage" + instrument: updowncounter + unit: "By" + attributes: + - ref: system.paging.state + + - id: metric.system.paging.utilization + type: metric + metric_name: system.paging.utilization + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.paging.state + + - id: metric.system.paging.faults + type: metric + metric_name: system.paging.faults + brief: "" + instrument: counter + unit: "{fault}" + attributes: + - ref: system.paging.type + + - id: metric.system.paging.operations + type: metric + metric_name: system.paging.operations + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.paging.type + - ref: system.paging.direction + + # system.disk.* metrics and attribute group + - id: attributes.system.disk + prefix: system.disk + type: attribute_group + brief: "Describes System Disk metric attributes" + attributes: + - id: direction + type: + allow_custom_values: false + members: + - id: read + value: 'read' + - id: write + value: 'write' + brief: "The disk operation direction" + examples: ["read"] + + - id: metric.system.disk.io + type: metric + metric_name: system.disk.io + brief: "" + instrument: counter + unit: "By" + attributes: + - ref: system.device + - ref: system.disk.direction + + - id: metric.system.disk.operations + type: metric + metric_name: system.disk.operations + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.device + - ref: system.disk.direction + + - id: metric.system.disk.io_time + type: metric + metric_name: system.disk.io_time + brief: "Time disk spent activated" + instrument: counter + unit: "s" + note: | + The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: + + - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) + - Windows: The complement of + ["Disk\% Idle Time"](https://learn.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` + attributes: + - ref: system.device + + - id: metric.system.disk.operation_time + type: metric + metric_name: system.disk.operation_time + brief: "Sum of the time each operation took to complete" + instrument: counter + unit: "s" + note: | + Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: + + - Linux: Fields 7 & 11 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) + - Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes) + attributes: + - ref: system.device + - ref: system.disk.direction + + - id: metric.system.disk.merged + type: metric + metric_name: system.disk.merged + brief: "" + instrument: counter + unit: "{operation}" + attributes: + - ref: system.device + - ref: system.disk.direction + + # system.filesystem.* metrics and attribute group + - id: attributes.system.filesystem + prefix: system.filesystem + type: attribute_group + brief: "Describes Filesystem metric attributes" + attributes: + - id: state + brief: "The filesystem state" + type: + allow_custom_values: false + members: + - id: used + value: 'used' + - id: free + value: 'free' + - id: reserved + value: 'reserved' + examples: ["used"] + - id: type + type: + allow_custom_values: true + members: + - id: fat32 + value: 'fat32' + - id: exfat + value: 'exfat' + - id: ntfs + value: 'ntfs' + - id: refs + value: 'refs' + - id: hfsplus + value: 'hfsplus' + - id: ext4 + value: 'ext4' + brief: "The filesystem type" + examples: ["ext4"] + - id: mode + type: string + brief: "The filesystem mode" + examples: ["rw, ro"] + - id: mountpoint + type: string + brief: "The filesystem mount path" + examples: ["/mnt/data"] + + - id: metric.system.filesystem.usage + type: metric + metric_name: system.filesystem.usage + brief: "" + instrument: updowncounter + unit: "By" + attributes: + - ref: system.device + - ref: system.filesystem.state + - ref: system.filesystem.type + - ref: system.filesystem.mode + - ref: system.filesystem.mountpoint + + - id: metric.system.filesystem.utilization + type: metric + metric_name: system.filesystem.utilization + brief: "" + instrument: gauge + unit: "1" + attributes: + - ref: system.device + - ref: system.filesystem.state + - ref: system.filesystem.type + - ref: system.filesystem.mode + - ref: system.filesystem.mountpoint + + # system.network.* metrics and attribute group + - id: attributes.system.network + prefix: system.network + type: attribute_group + brief: "Describes Network metric attributes" + attributes: + - id: direction + type: + allow_custom_values: false + members: + - id: transmit + value: 'transmit' + - id: receive + value: 'receive' + brief: "" + examples: ["transmit"] + - id: state + type: + allow_custom_values: false + members: + - id: close + value: 'close' + - id: close_wait + value: 'close_wait' + - id: closing + value: 'closing' + - id: delete + value: 'delete' + - id: established + value: 'established' + - id: fin_wait_1 + value: 'fin_wait_1' + - id: fin_wait_2 + value: 'fin_wait_2' + - id: last_ack + value: 'last_ack' + - id: listen + value: 'listen' + - id: syn_recv + value: 'syn_recv' + - id: syn_sent + value: 'syn_sent' + - id: time_wait + value: 'time_wait' + brief: "A stateless protocol MUST NOT set this attribute" + examples: ["close_wait"] + + - id: metric.system.network.dropped + type: metric + metric_name: system.network.dropped + brief: "Count of packets that are dropped or discarded even though there was no error" + instrument: counter + unit: "{packet}" + note: | + Measured as: + + - Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)) + - Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2) + attributes: + - ref: system.device + - ref: system.network.direction + + - id: metric.system.network.packets + type: metric + metric_name: system.network.packets + brief: "" + instrument: counter + unit: "{packet}" + attributes: + - ref: system.device + - ref: system.network.direction + + - id: metric.system.network.errors + type: metric + metric_name: system.network.errors + brief: "Count of network errors detected" + instrument: counter + unit: "{error}" + note: | + Measured as: + + - Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). + - Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). + attributes: + - ref: system.device + - ref: system.network.direction + + - id: metric.system.network.io + type: metric + metric_name: system.network.io + brief: "" + instrument: counter + unit: "By" + attributes: + - ref: system.device + - ref: system.network.direction + + - id: metric.system.network.connections + type: metric + metric_name: system.network.connections + brief: "" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: system.device + - ref: system.network.state + - ref: network.transport + + # system.processes.* metrics and attribute group + - id: attributes.system.processes + prefix: system.processes + type: attribute_group + brief: "Describes System Process metric attributes" + attributes: + - id: status + type: + allow_custom_values: true + members: + - id: running + value: 'running' + - id: sleeping + value: 'sleeping' + - id: stopped + value: 'stopped' + - id: defunct + value: 'defunct' + brief: > + The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) + examples: ["running"] + + + - id: metric.system.processes.count + type: metric + metric_name: system.processes.count + brief: "Total number of processes in each state" + instrument: updowncounter + unit: "{process}" + attributes: + - ref: system.processes.status + + - id: metric.system.processes.created + type: metric + metric_name: system.processes.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 acc97ca7b8..609605b787 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -63,6 +63,70 @@ versions: - 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 1.21.0: spans: changes: From 48dc44c31ba8132b8d02e4452cf7bca972d637fb Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Tue, 12 Sep 2023 18:55:20 +0300 Subject: [PATCH 20/25] Bump semantic conventions tooling to v0.21.0 (#310) Co-authored-by: Armin Ruech --- .vscode/settings.json | 2 +- Makefile | 2 +- internal/tools/schema_check.sh | 2 +- model/README.md | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 89d895f2f4..6b792056bd 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.20.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.21.0/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index 0a7bed5ae5..a87243775e 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.20.0 +SEMCONVGEN_VERSION=0.21.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 179ca4087b..f89a391e2b 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.20.0 +BUILD_TOOL_SCHEMAS_VERSION=0.21.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/model/README.md b/model/README.md index b8afe3e506..b80573074f 100644 --- a/model/README.md +++ b/model/README.md @@ -14,12 +14,12 @@ Semantic conventions for the spec MUST adhere to the [attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md), and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -30,7 +30,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. From 58c52c59bae610f637cff57541aeb55d29788573 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 12 Sep 2023 09:01:35 -0700 Subject: [PATCH 21/25] Update client address to be consistent with server address (#302) Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 ++ docs/general/attributes.md | 2 +- docs/http/http-spans.md | 2 +- docs/rpc/rpc-spans.md | 2 +- model/client.yaml | 2 +- 5 files changed, 6 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4612cb77e9..96acda87f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,8 @@ release. ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) - Moved RPC streaming notes from metric brief section to notes section. ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275)) +- Updates `client.address` to allow domain names for consistency with `server.address`. + ([#302](https://github.com/open-telemetry/semantic-conventions/pull/302)) - BREAKING: Generate System metrics semconv from YAML. ([#89](https://github.com/open-telemetry/semantic-conventions/pull/89)) - Rename attributes for `system.cpu.*` metrics: diff --git a/docs/general/attributes.md b/docs/general/attributes.md index b1bc6e0ff6..f4199c7e0f 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -128,7 +128,7 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `client.address` | string | Client address - IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | +| `client.address` | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | | `client.port` | int | Client port number. [2] | `65123` | Recommended | | `client.socket.address` | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | `client.socket.port` | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 2fa3121bb9..861cc74fab 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -376,7 +376,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`client.address`](../general/attributes.md) | string | Client address - IP address or Unix domain socket name. [2] | `83.164.160.102` | Recommended | +| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `83.164.160.102` | Recommended | | [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | | [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [4] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [5] | `35555` | Recommended: If different than `client.port`. | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index e5bdaaf29d..7ef19bc619 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -161,7 +161,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`client.address`](../general/attributes.md) | string | Client address - IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | +| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | | [`client.port`](../general/attributes.md) | int | Client port number. [2] | `65123` | Recommended | | [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | diff --git a/model/client.yaml b/model/client.yaml index 51fbb636f2..d1d9502183 100644 --- a/model/client.yaml +++ b/model/client.yaml @@ -12,7 +12,7 @@ groups: attributes: - id: address type: string - brief: Client address - IP address or Unix domain socket name. + brief: Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. note: > When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. From e880bddb63437119a33caddd643e069b500851a6 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 13 Sep 2023 13:11:19 +0200 Subject: [PATCH 22/25] Fix System metrics yaml warning (#322) --- model/metrics/system-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 41c508f3d2..2759d1f66f 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -452,7 +452,7 @@ groups: - ref: system.network.state - ref: network.transport - # system.processes.* metrics and attribute group + # system.processes.* metrics and attribute group - id: attributes.system.processes prefix: system.processes type: attribute_group From 875cfefe7d143aca5258c625c98d87d3c95aba46 Mon Sep 17 00:00:00 2001 From: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> Date: Mon, 18 Sep 2023 09:44:11 -0600 Subject: [PATCH 23/25] Reduce restrictions on which metrics may be named utilization (#280) --- docs/general/metrics.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 938a5e73e1..c4c6398fbf 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -166,8 +166,10 @@ over all attribute values SHOULD be equal to the **limit**. - **utilization** - an instrument that measures the *fraction* of **usage** out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization -values are in the range `[0, 1]`. +`system.memory.utilization` for the fraction of memory in use. Utilization can +be with respect to a fixed limit or a soft limit. Utilization values are +represended as a ratio and are typically in the range `[0, 1]`, but may go above 1 +in case of exceeding a soft limit. - **time** - an instrument that measures passage of time should be called `entity.time`. For example, `system.cpu.time` with attribute `state = idle | user From a5979b01bd4549da6868bc8c97bf5a904f154be0 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 19 Sep 2023 12:37:12 +0200 Subject: [PATCH 24/25] Make messaging payload attributes consistent with other conventions (#229) Co-authored-by: Alexander Wert Co-authored-by: Joao Grassi --- CHANGELOG.md | 3 +++ docs/messaging/messaging-spans.md | 44 ++++++++++++++++++------------- model/trace/messaging.yaml | 22 ++++++++++------ schema-next.yaml | 4 +++ 4 files changed, 46 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96acda87f4..4d6974e789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -100,6 +100,9 @@ release. - `state` to `system.network.state` - Rename attributes for `system.processes.*` metrics: - `status` to `system.processes.status` +- BREAKING: Rename `messaging.message.payload_size_bytes` to `messaging.message.body.size`, + remove `messaging.message.payload_compressed_size_bytes`. + ([#229](https://github.com/open-telemetry/semantic-conventions/pull/229)) ## v1.21.0 (2023-07-13) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index c1814ad8d9..6135222dc0 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -66,7 +66,7 @@ Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): -A *message* is an envelope with a potentially empty payload. +A *message* is an envelope with a potentially empty body. This envelope may offer the possibility to convey additional metadata, often in key/value form. A message is sent by a message *producer* to: @@ -225,18 +225,18 @@ The following operations related to messages are defined for these semantic conv | `messaging.destination.name` | string | The message destination name [5] | `MyQueue`; `MyTopic` | Conditionally Required: [6] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | Conditionally Required: [8] | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [9] | -| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [10] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [11] | -| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [12] | -| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [13] | +| `messaging.message.body.size` | int | The size of the message body in bytes. [10] | `1439` | Recommended: [11] | +| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [12] | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [13] | `2738` | Recommended: [14] | +| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [15] | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [16] | `3.1.1` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [15] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [16] | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [17] | `proxy.example.com` | Recommended: [18] | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [19] | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [17] | `example.com` | Conditionally Required: If available. | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [18] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [19] | `proxy.example.com` | Recommended: [20] | +| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [21] | `16456` | Recommended: If different than `server.port`. | **[1]:** If a custom value is used, it MUST be of low cardinality. @@ -257,26 +257,32 @@ the broker does not have such notion, the destination name SHOULD uniquely ident **[9]:** If value is `true`. When missing, the value is assumed to be `false`. -**[10]:** Only if span represents operation on a single message. +**[10]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. -**[11]:** Only for spans that represent an operation on a single message. +**[11]:** Only if span represents operation on a single message. **[12]:** Only if span represents operation on a single message. -**[13]:** Only if span represents operation on a single message. +**[13]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. -**[14]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[14]:** Only if span represents operation on a single message. -**[15]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[15]:** Only for spans that represent an operation on a single message. -**[16]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[17]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[18]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -**[17]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +**[19]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. -**[18]:** If different than `server.address` and if `server.socket.address` is set. +**[20]:** If different than `server.address` and if `server.socket.address` is set. -**[19]:** When observed from the client side, this SHOULD represent the immediate server peer port. +**[21]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. `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. diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index bb7a768638..19c8f375ed 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -15,16 +15,22 @@ groups: The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". examples: 'MyConversationId' - - id: message.payload_size_bytes + - id: message.envelope.size type: int brief: > - The (uncompressed) size of the message payload in bytes. - Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. + The size of the message body and metadata in bytes. + note: | + This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed + size should be used. examples: 2738 - - id: message.payload_compressed_size_bytes + - id: message.body.size type: int - brief: 'The compressed size of the message payload in bytes.' - examples: 2048 + brief: > + The size of the message body in bytes. + note: | + 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 - id: messaging.destination prefix: messaging.destination @@ -156,10 +162,10 @@ groups: - ref: messaging.message.conversation_id requirement_level: recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_size_bytes + - ref: messaging.message.envelope.size requirement_level: recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_compressed_size_bytes + - ref: messaging.message.body.size requirement_level: recommended: Only if span represents operation on a single message. - ref: server.address diff --git a/schema-next.yaml b/schema-next.yaml index 609605b787..7e82205757 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,10 @@ versions: next: metrics: 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/semantic-conventions/pull/224 - rename_metrics: http.client.duration: http.client.request.duration From 203691d99612452df0c951640b04521e34969628 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 20 Sep 2023 09:49:31 -0700 Subject: [PATCH 25/25] Improve `error.type` wording in HTTP semconv (#331) --- docs/http/http-metrics.md | 12 ++++++------ docs/http/http-spans.md | 2 +- model/http-common.yaml | 2 +- model/metrics/http.yaml | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 07c065f2ab..c41cf7c61a 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -93,7 +93,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -263,7 +263,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -365,7 +365,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -469,7 +469,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -565,7 +565,7 @@ This metric is optional. `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -661,7 +661,7 @@ This metric is optional. `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 861cc74fab..914a859f0c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -134,7 +134,7 @@ sections below. `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. diff --git a/model/http-common.yaml b/model/http-common.yaml index b6643676db..7d062bd584 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -71,7 +71,7 @@ groups: `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index f6354aa7d5..c0e241b9c7 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -40,7 +40,7 @@ groups: `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -76,7 +76,7 @@ groups: `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code. + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report.