From 5b18d0035eba76340b7baa4cfec1296a71b9b0fa Mon Sep 17 00:00:00 2001 From: braydonk Date: Mon, 18 Sep 2023 18:56:52 +0000 Subject: [PATCH 01/13] metrics: add process-metrics.yaml --- CHANGELOG.md | 12 ++ docs/system/process-metrics.md | 183 ++++++++++++++++++++++++++--- model/metrics/process-metrics.yaml | 137 +++++++++++++++++++++ 3 files changed, 314 insertions(+), 18 deletions(-) create mode 100644 model/metrics/process-metrics.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dfe18a4a3..d703e75536 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -203,6 +203,18 @@ stabilized. ([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) - Add `container.labels.` attributes. ([#125](https://github.com/open-telemetry/semantic-conventions/pull/125)) +- BREAKING: Generate process metrics from YAML + ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) + - Rename attributes for `process.cpu.*` + - `state` to `process.cpu.state` + - Rename attributes for `process.disk.io` + - `direction` to `process.disk.io.direction` + - Rename attributes for `process.network.io` + - `direction` to `process.network.io.direction` + - Rename attributes for `process.context_switches` + - `type` to `process.context_switches.type` + - Rename attributes for `process.paging.faults` + - `type` to `process.paging.faults.type` - 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} diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index c619763717..e69c5585aa 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -20,8 +20,15 @@ metrics](/docs/runtime/README.md#metrics). - [Metric Instruments](#metric-instruments) - * [Process](#process) -- [Attributes](#attributes) + * [Metric: `process.cpu.time`](#metric-processcputime) + * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + * [Metric: `process.memory.usage`](#metric-processmemoryusage) + * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + * [Metric: `process.disk.io`](#metric-processdiskio) + * [Metric: `process.network.io`](#metric-processnetworkio) + * [Metric: `process.threads`](#metric-processthreads) + * [Metric: `process.context_switches`](#metric-processcontext_switches) + * [Metric: `process.paging.faults`](#metric-processpagingfaults) @@ -37,25 +44,165 @@ metrics](/docs/runtime/README.md#metrics). ## Metric Instruments -### Process +### Metric: `process.cpu.time` -Below is a table of Process metric instruments. + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | + -| Name | Instrument Type ([\*](/docs/general/metrics.md#instrument-types)) | Unit | Description | Labels | -|---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.memory.usage` | UpDownCounter | By | The amount of physical memory in use. | | -| `process.memory.virtual` | UpDownCounter | By | The amount of committed virtual memory. | | -| `process.disk.io` | Counter | By | Disk bytes transferred. | `direction` SHOULD be one of: `read`, `write` | -| `process.network.io` | Counter | By | Network bytes transferred. | `direction` SHOULD be one of: `receive`, `transmit` | -| `process.threads` | UpDownCounter | {thread} | Process threads count. | | -| `process.open_file_descriptors` | UpDownCounter | {count} | Number of file descriptors in use by the process. | | -| `process.context_switches` | Counter | {count} | Number of times the process has been context switched. | `type` SHOULD be one of: `involuntary`, `voluntary` | -| `process.paging.faults` | Counter | {fault} | Number of page faults the process has made. | `type`, if specified, SHOULD be one of: `major` (for major, or hard, page faults), `minor` (for minor, or soft, page faults). | + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | -## Attributes +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -Process metrics SHOULD be associated with a [`process`](/docs/resource/process.md#process) resource whose attributes provide additional context about the process. +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | + + +### Metric: `process.cpu.utilization` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | + +`process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | + + +### Metric: `process.memory.usage` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | + + + + + +### Metric: `process.memory.virtual` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | + + + + + +### Metric: `process.disk.io` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.disk.io` | Counter | `By` | Disk bytes transferred. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.disk.process.disk.io.direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | + +`process.disk.process.disk.io.direction` 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 | +|---|---| +| `read` | read | +| `write` | write | + + +### Metric: `process.network.io` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.network.io` | Counter | `By` | Network bytes transferred. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.network.io.direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | + +`process.network.io.direction` 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 | +|---|---| +| `receive` | receive | +| `transmit` | transmit | + + +### Metric: `process.threads` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.threads` | UpDownCounter | `{thread}` | Process threads count. | + + + + + +### Metric: `process.context_switches` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.context_switches.type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | + +`process.context_switches.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `voluntary` | voluntary | +| `involuntary` | involuntary | + + +### Metric: `process.paging.faults` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.paging.faults` | UpDownCounter | `{fault}` | Number of page faults the process has made. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.paging.faults.type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | + +`process.paging.faults.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `major` | major | +| `minor` | minor | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml new file mode 100644 index 0000000000..5100e37bc6 --- /dev/null +++ b/model/metrics/process-metrics.yaml @@ -0,0 +1,137 @@ +groups: + - id: attributes.process.cpu + prefix: process.cpu + type: attribute_group + brief: "Attributes for process CPU metrics." + attributes: + - id: state + brief: "The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels." + type: + allow_custom_values: true + members: + - id: system + value: 'system' + - id: user + value: 'user' + - id: wait + value: 'wait' + + - id: metric.process.cpu.time + type: metric + metric_name: process.cpu.time + brief: "Total CPU seconds broken down by different states." + instrument: counter + unit: "s" + attributes: + - ref: process.cpu.state + + - id: metric.process.cpu.utilization + type: metric + metric_name: process.cpu.utilization + brief: "Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process." + instrument: gauge + unit: "1" + attributes: + - ref: process.cpu.state + + - id: metric.process.memory.usage + type: metric + metric_name: process.memory.usage + brief: "The amount of physical memory in use." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.memory.virtual + type: metric + metric_name: process.memory.virtual + brief: "The amount of committed virtual memory." + instrument: updowncounter + unit: "By" + attributes: [] + + - id: metric.process.disk.io + type: metric + metric_name: process.disk.io + prefix: process.disk + brief: "Disk bytes transferred." + instrument: counter + unit: "By" + attributes: + - id: process.disk.io.direction + brief: "The direction of the data transfer for this data point." + type: + allow_custom_values: true + members: + - id: read + value: 'read' + - id: write + value: 'write' + + - id: metric.process.network.io + type: metric + metric_name: process.network.io + brief: "Network bytes transferred." + instrument: counter + unit: "By" + attributes: + - id: process.network.io.direction + brief: "The direction of the data transfer for this data point." + type: + allow_custom_values: true + members: + - id: receive + value: 'receive' + - id: transmit + value: 'transmit' + + - id: metric.process.threads + type: metric + metric_name: process.threads + brief: "Process threads count." + instrument: updowncounter + unit: "{thread}" + attributes: [] + + - id: metric.process.open_file_descriptors + type: metric + metric_name: process.open_file_descriptors + brief: "Number of file descriptors in use by the process." + instrument: updowncounter + unit: "{count}" + attributes: [] + + - id: metric.process.context_switches + type: metric + metric_name: process.context_switches + brief: "Number of times the process has been context switched." + instrument: counter + unit: "{count}" + attributes: + - id: process.context_switches.type + brief: "Specifies whether the context switches for this data point were voluntary or involuntary." + type: + allow_custom_values: true + members: + - id: voluntary + value: 'voluntary' + - id: involuntary + value: 'involuntary' + + - id: metric.process.paging.faults + type: metric + metric_name: process.paging.faults + brief: "Number of page faults the process has made." + instrument: updowncounter + unit: "{fault}" + attributes: + - id: process.paging.faults.type + brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." + type: + allow_custom_values: true + members: + - id: major + value: 'major' + - id: minor + value: 'minor' + From fdf90ea010775446d73a33bc19bb1d0860044974 Mon Sep 17 00:00:00 2001 From: braydonk Date: Tue, 19 Sep 2023 13:29:58 +0000 Subject: [PATCH 02/13] Fix lint errors, add ignore to .yamllint Fixes linting errors, also adds the `ignore-from-file` configuration the the `.yamllint` to avoid scanning `node_modules` locally. --- .yamllint | 3 +++ CHANGELOG.md | 7 +++++++ model/metrics/process-metrics.yaml | 1 - 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.yamllint b/.yamllint index 39c91cefa1..70b17e868b 100644 --- a/.yamllint +++ b/.yamllint @@ -1,5 +1,8 @@ extends: default +ignore-from-file: + - .gitignore + rules: document-start: disable octal-values: enable diff --git a/CHANGELOG.md b/CHANGELOG.md index d703e75536..746dd7c3ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -206,6 +206,13 @@ stabilized. - BREAKING: Generate process metrics from YAML ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - Rename attributes for `process.cpu.*` +======= +- BREAKING: Generate process metrics from YAML + ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) + - Rename attributes for `process.cpu.time` + - `state` to `process.cpu.state` + - Rename attributes for `process.cpu.utilization` +>>>>>>> 3e1bee7 (Fix lint errors, add ignore to .yamllint) - `state` to `process.cpu.state` - Rename attributes for `process.disk.io` - `direction` to `process.disk.io.direction` diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 5100e37bc6..9333a579b7 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -134,4 +134,3 @@ groups: value: 'major' - id: minor value: 'minor' - From aee0ef6876b01525ff623cb648681af545f13734 Mon Sep 17 00:00:00 2001 From: braydonk Date: Tue, 10 Oct 2023 15:36:49 +0000 Subject: [PATCH 03/13] address comments, fix conflicts in progress 2 in progress 3 --- docs/system/process-metrics.md | 36 +++++++++++++++++++++--------- model/metrics/process-metrics.yaml | 2 +- schema-next.yaml | 27 ++++++++++++++++++++++ 3 files changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index e69c5585aa..678acf0227 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -19,16 +19,18 @@ metrics](/docs/runtime/README.md#metrics). -- [Metric Instruments](#metric-instruments) - * [Metric: `process.cpu.time`](#metric-processcputime) - * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) - * [Metric: `process.memory.usage`](#metric-processmemoryusage) - * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) - * [Metric: `process.disk.io`](#metric-processdiskio) - * [Metric: `process.network.io`](#metric-processnetworkio) - * [Metric: `process.threads`](#metric-processthreads) - * [Metric: `process.context_switches`](#metric-processcontext_switches) - * [Metric: `process.paging.faults`](#metric-processpagingfaults) +- [Semantic Conventions for OS Process Metrics](#semantic-conventions-for-os-process-metrics) + - [Metric Instruments](#metric-instruments) + - [Metric: `process.cpu.time`](#metric-processcputime) + - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + - [Metric: `process.memory.usage`](#metric-processmemoryusage) + - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + - [Metric: `process.disk.io`](#metric-processdiskio) + - [Metric: `process.network.io`](#metric-processnetworkio) + - [Metric: `process.threads`](#metric-processthreads) + - [Metric: `process.open_file_descriptors`](#metric-processopen_file_descriptors) + - [Metric: `process.context_switches`](#metric-processcontext_switches) + - [Metric: `process.paging.faults`](#metric-processpagingfaults) @@ -163,6 +165,18 @@ metrics](/docs/runtime/README.md#metrics). +### Metric: `process.open_file_descriptors` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | + + + + + + ### Metric: `process.context_switches` @@ -189,7 +203,7 @@ metrics](/docs/runtime/README.md#metrics). | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.paging.faults` | UpDownCounter | `{fault}` | Number of page faults the process has made. | +| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 9333a579b7..ce923afc7f 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -122,7 +122,7 @@ groups: type: metric metric_name: process.paging.faults brief: "Number of page faults the process has made." - instrument: updowncounter + instrument: counter unit: "{fault}" attributes: - id: process.paging.faults.type diff --git a/schema-next.yaml b/schema-next.yaml index 58de42a543..e7011d6b6e 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -180,6 +180,33 @@ versions: - rename_metrics: http.server.request.size: http.server.request.body.size http.server.response.size: http.server.response.body.size + # https://github.com/open-telemetry/semantic-conventions/pull/330 + - rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization + - rename_attributes: + attribute_map: + direction: process.disk.io.direction + apply_to_metrics: + - process.disk.io + - rename_attributes: + attribute_map: + type: process.context_switches.type + apply_to_metrics: + - process.context_switches + - rename_attributes: + attribute_map: + direction: process.network.io.direction + apply_to_metrics: + - process.network.io + - rename_attributes: + attribute_map: + type: process.paging.faults.type + apply_to_metrics: + - process.paging.faults resources: changes: # https://github.com/open-telemetry/semantic-conventions/pull/178 From c6909b3e04cd57308c944de0f7a6da4a5e606b03 Mon Sep 17 00:00:00 2001 From: braydonk Date: Tue, 10 Oct 2023 19:10:54 +0000 Subject: [PATCH 04/13] adding conflict fix I forgot to save --- CHANGELOG.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 746dd7c3ee..30c46f6eed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ release. ## Unreleased +<<<<<<< HEAD ### Breaking - Rename `system.processes.*` namespace to `system.process.*` @@ -199,6 +200,8 @@ stabilized. ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) +======= +>>>>>>> 0f8b883 (adding conflict fix I forgot to save) - Adds `session.id` and session.md to general docs and model ([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) - Add `container.labels.` attributes. @@ -206,13 +209,6 @@ stabilized. - BREAKING: Generate process metrics from YAML ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - Rename attributes for `process.cpu.*` -======= -- BREAKING: Generate process metrics from YAML - ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - - Rename attributes for `process.cpu.time` - - `state` to `process.cpu.state` - - Rename attributes for `process.cpu.utilization` ->>>>>>> 3e1bee7 (Fix lint errors, add ignore to .yamllint) - `state` to `process.cpu.state` - Rename attributes for `process.disk.io` - `direction` to `process.disk.io.direction` From 9e3acf34d7458189967db8b5bbc2ada137b0548f Mon Sep 17 00:00:00 2001 From: braydonk Date: Wed, 11 Oct 2023 18:31:01 +0000 Subject: [PATCH 05/13] generate toc, fix markdownlint --- docs/system/process-metrics.md | 147 ++++++++++++++++----------------- 1 file changed, 73 insertions(+), 74 deletions(-) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 678acf0227..5835ac72b7 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -49,53 +49,53 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.cpu.time` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ------------------ | --------------- | ----------- | -------------------------------------------------- | +| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -|---|---| -| `system` | system | -| `user` | user | -| `wait` | wait | +| Value | Description | +| -------- | ----------- | +| `system` | system | +| `user` | user | +| `wait` | wait | ### Metric: `process.cpu.utilization` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ------------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -|---|---| -| `system` | system | -| `user` | user | -| `wait` | wait | +| Value | Description | +| -------- | ----------- | +| `system` | system | +| `user` | user | +| `wait` | wait | ### Metric: `process.memory.usage` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ---------------------- | --------------- | ----------- | ------------------------------------- | +| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | @@ -104,9 +104,9 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.memory.virtual` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ------------------------ | --------------- | ----------- | --------------------------------------- | +| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | @@ -115,51 +115,51 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.disk.io` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.disk.io` | Counter | `By` | Disk bytes transferred. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ----------------- | --------------- | ----------- | ----------------------- | +| `process.disk.io` | Counter | `By` | Disk bytes transferred. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.disk.process.disk.io.direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ---------------------------------------- | ------ | ------------------------------------------------------- | -------- | ----------------- | +| `process.disk.process.disk.io.direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | `process.disk.process.disk.io.direction` 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 | -|---|---| -| `read` | read | -| `write` | write | +| Value | Description | +| ------- | ----------- | +| `read` | read | +| `write` | write | ### Metric: `process.network.io` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.network.io` | Counter | `By` | Network bytes transferred. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------------------- | --------------- | ----------- | -------------------------- | +| `process.network.io` | Counter | `By` | Network bytes transferred. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.network.io.direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ------------------------------ | ------ | ------------------------------------------------------- | --------- | ----------------- | +| `process.network.io.direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | `process.network.io.direction` 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 | -|---|---| -| `receive` | receive | -| `transmit` | transmit | +| Value | Description | +| ---------- | ----------- | +| `receive` | receive | +| `transmit` | transmit | ### Metric: `process.threads` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.threads` | UpDownCounter | `{thread}` | Process threads count. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ----------------- | --------------- | ----------- | ---------------------- | +| `process.threads` | UpDownCounter | `{thread}` | Process threads count. | @@ -168,55 +168,54 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.open_file_descriptors` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ------------------------------- | --------------- | ----------- | ------------------------------------------------- | +| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | - ### Metric: `process.context_switches` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------------------------- | --------------- | ----------- | ------------------------------------------------------ | +| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.context_switches.type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ------------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------- | ----------------- | +| `process.context_switches.type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | `process.context_switches.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -|---|---| -| `voluntary` | voluntary | +| Value | Description | +| ------------- | ----------- | +| `voluntary` | voluntary | | `involuntary` | involuntary | ### Metric: `process.paging.faults` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | +| Name | Instrument Type | Unit (UCUM) | Description | +| ----------------------- | --------------- | ----------- | ------------------------------------------- | +| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.paging.faults.type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | +| `process.paging.faults.type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | `process.paging.faults.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -|---|---| -| `major` | major | -| `minor` | minor | +| Value | Description | +| ------- | ----------- | +| `major` | major | +| `minor` | minor | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md From fe0f2d723343f95372c040040c8d0bfbb1a0a66e Mon Sep 17 00:00:00 2001 From: Braydon Kains Date: Tue, 7 Nov 2023 10:01:20 -0600 Subject: [PATCH 06/13] rename metrics and attributes for spec compliance Rename metrics that are updowncounters to use the `.count` naming convention. Also rename attributes to not use metric names as namespaces. --- CHANGELOG.md | 15 --- docs/system/process-metrics.md | 189 ++++++++++++++--------------- model/metrics/process-metrics.yaml | 14 +-- schema-next.yaml | 27 ----- 4 files changed, 101 insertions(+), 144 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30c46f6eed..4dfe18a4a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,6 @@ release. ## Unreleased -<<<<<<< HEAD ### Breaking - Rename `system.processes.*` namespace to `system.process.*` @@ -200,24 +199,10 @@ stabilized. ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) -======= ->>>>>>> 0f8b883 (adding conflict fix I forgot to save) - Adds `session.id` and session.md to general docs and model ([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) - Add `container.labels.` attributes. ([#125](https://github.com/open-telemetry/semantic-conventions/pull/125)) -- BREAKING: Generate process metrics from YAML - ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - - Rename attributes for `process.cpu.*` - - `state` to `process.cpu.state` - - Rename attributes for `process.disk.io` - - `direction` to `process.disk.io.direction` - - Rename attributes for `process.network.io` - - `direction` to `process.network.io.direction` - - Rename attributes for `process.context_switches` - - `type` to `process.context_switches.type` - - Rename attributes for `process.paging.faults` - - `type` to `process.paging.faults.type` - 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} diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 5835ac72b7..867899d0c6 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -19,18 +19,17 @@ metrics](/docs/runtime/README.md#metrics). -- [Semantic Conventions for OS Process Metrics](#semantic-conventions-for-os-process-metrics) - - [Metric Instruments](#metric-instruments) - - [Metric: `process.cpu.time`](#metric-processcputime) - - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) - - [Metric: `process.memory.usage`](#metric-processmemoryusage) - - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) - - [Metric: `process.disk.io`](#metric-processdiskio) - - [Metric: `process.network.io`](#metric-processnetworkio) - - [Metric: `process.threads`](#metric-processthreads) - - [Metric: `process.open_file_descriptors`](#metric-processopen_file_descriptors) - - [Metric: `process.context_switches`](#metric-processcontext_switches) - - [Metric: `process.paging.faults`](#metric-processpagingfaults) +- [Metric Instruments](#metric-instruments) + * [Metric: `process.cpu.time`](#metric-processcputime) + * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + * [Metric: `process.memory.usage`](#metric-processmemoryusage) + * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + * [Metric: `process.disk.io`](#metric-processdiskio) + * [Metric: `process.network.io`](#metric-processnetworkio) + * [Metric: `process.thread.count`](#metric-processthreadcount) + * [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + * [Metric: `process.context_switches`](#metric-processcontext_switches) + * [Metric: `process.paging.faults`](#metric-processpagingfaults) @@ -49,53 +48,53 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.cpu.time` -| Name | Instrument Type | Unit (UCUM) | Description | -| ------------------ | --------------- | ----------- | -------------------------------------------------- | -| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.time` | Counter | `s` | Total CPU seconds broken down by different states. | -| Attribute | Type | Description | Examples | Requirement Level | -| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | -| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -| -------- | ----------- | -| `system` | system | -| `user` | user | -| `wait` | wait | +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | ### Metric: `process.cpu.utilization` -| Name | Instrument Type | Unit (UCUM) | Description | -| ------------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.cpu.utilization` | Gauge | `1` | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | -| Attribute | Type | Description | Examples | Requirement Level | -| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | -| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.cpu.state` | string | The CPU state for this data point. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `system` | Recommended | `process.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -| -------- | ----------- | -| `system` | system | -| `user` | user | -| `wait` | wait | +| Value | Description | +|---|---| +| `system` | system | +| `user` | user | +| `wait` | wait | ### Metric: `process.memory.usage` -| Name | Instrument Type | Unit (UCUM) | Description | -| ---------------------- | --------------- | ----------- | ------------------------------------- | -| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.usage` | UpDownCounter | `By` | The amount of physical memory in use. | @@ -104,9 +103,9 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.memory.virtual` -| Name | Instrument Type | Unit (UCUM) | Description | -| ------------------------ | --------------- | ----------- | --------------------------------------- | -| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.memory.virtual` | UpDownCounter | `By` | The amount of committed virtual memory. | @@ -115,107 +114,107 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.disk.io` -| Name | Instrument Type | Unit (UCUM) | Description | -| ----------------- | --------------- | ----------- | ----------------------- | -| `process.disk.io` | Counter | `By` | Disk bytes transferred. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.disk.io` | Counter | `By` | Disk bytes transferred. | -| Attribute | Type | Description | Examples | Requirement Level | -| ---------------------------------------- | ------ | ------------------------------------------------------- | -------- | ----------------- | -| `process.disk.process.disk.io.direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.disk.process.disk.io_direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | -`process.disk.process.disk.io.direction` 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. +`process.disk.process.disk.io_direction` 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 | -| ------- | ----------- | -| `read` | read | -| `write` | write | +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | ### Metric: `process.network.io` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------------------- | --------------- | ----------- | -------------------------- | -| `process.network.io` | Counter | `By` | Network bytes transferred. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.network.io` | Counter | `By` | Network bytes transferred. | -| Attribute | Type | Description | Examples | Requirement Level | -| ------------------------------ | ------ | ------------------------------------------------------- | --------- | ----------------- | -| `process.network.io.direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.network.io_direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | -`process.network.io.direction` 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. +`process.network.io_direction` 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 | -| ---------- | ----------- | -| `receive` | receive | -| `transmit` | transmit | +| Value | Description | +|---|---| +| `receive` | receive | +| `transmit` | transmit | -### Metric: `process.threads` +### Metric: `process.thread.count` - -| Name | Instrument Type | Unit (UCUM) | Description | -| ----------------- | --------------- | ----------- | ---------------------- | -| `process.threads` | UpDownCounter | `{thread}` | Process threads count. | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.thread.count` | UpDownCounter | `{thread}` | Process threads count. | - + -### Metric: `process.open_file_descriptors` +### Metric: `process.open_file_descriptor.count` - -| Name | Instrument Type | Unit (UCUM) | Description | -| ------------------------------- | --------------- | ----------- | ------------------------------------------------- | -| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | - + ### Metric: `process.context_switches` -| Name | Instrument Type | Unit (UCUM) | Description | -| -------------------------- | --------------- | ----------- | ------------------------------------------------------ | -| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.context_switches` | Counter | `{count}` | Number of times the process has been context switched. | -| Attribute | Type | Description | Examples | Requirement Level | -| ------------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------- | ----------------- | -| `process.context_switches.type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.context_switch_type` | string | Specifies whether the context switches for this data point were voluntary or involuntary. | `voluntary` | Recommended | -`process.context_switches.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. +`process.context_switch_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -| ------------- | ----------- | -| `voluntary` | voluntary | +| Value | Description | +|---|---| +| `voluntary` | voluntary | | `involuntary` | involuntary | ### Metric: `process.paging.faults` -| Name | Instrument Type | Unit (UCUM) | Description | -| ----------------------- | --------------- | ----------- | ------------------------------------------- | -| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.paging.faults` | Counter | `{fault}` | Number of page faults the process has made. | -| Attribute | Type | Description | Examples | Requirement Level | -| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | -| `process.paging.faults.type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `process.paging.fault_type` | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major` | Recommended | -`process.paging.faults.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. +`process.paging.fault_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -| Value | Description | -| ------- | ----------- | -| `major` | major | -| `minor` | minor | +| Value | Description | +|---|---| +| `major` | major | +| `minor` | minor | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index ce923afc7f..7ccc0f3549 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -58,7 +58,7 @@ groups: instrument: counter unit: "By" attributes: - - id: process.disk.io.direction + - id: process.disk.io_direction brief: "The direction of the data transfer for this data point." type: allow_custom_values: true @@ -75,7 +75,7 @@ groups: instrument: counter unit: "By" attributes: - - id: process.network.io.direction + - id: process.network.io_direction brief: "The direction of the data transfer for this data point." type: allow_custom_values: true @@ -85,15 +85,15 @@ groups: - id: transmit value: 'transmit' - - id: metric.process.threads + - id: metric.process.thread.count type: metric - metric_name: process.threads + metric_name: process.thread.count brief: "Process threads count." instrument: updowncounter unit: "{thread}" attributes: [] - - id: metric.process.open_file_descriptors + - id: metric.process.open_file_descriptor.count type: metric metric_name: process.open_file_descriptors brief: "Number of file descriptors in use by the process." @@ -108,7 +108,7 @@ groups: instrument: counter unit: "{count}" attributes: - - id: process.context_switches.type + - id: process.context_switch_type brief: "Specifies whether the context switches for this data point were voluntary or involuntary." type: allow_custom_values: true @@ -125,7 +125,7 @@ groups: instrument: counter unit: "{fault}" attributes: - - id: process.paging.faults.type + - id: process.paging.fault_type brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." type: allow_custom_values: true diff --git a/schema-next.yaml b/schema-next.yaml index e7011d6b6e..58de42a543 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -180,33 +180,6 @@ versions: - rename_metrics: http.server.request.size: http.server.request.body.size http.server.response.size: http.server.response.body.size - # https://github.com/open-telemetry/semantic-conventions/pull/330 - - rename_attributes: - attribute_map: - state: process.cpu.state - apply_to_metrics: - - process.cpu.time - - process.cpu.utilization - - rename_attributes: - attribute_map: - direction: process.disk.io.direction - apply_to_metrics: - - process.disk.io - - rename_attributes: - attribute_map: - type: process.context_switches.type - apply_to_metrics: - - process.context_switches - - rename_attributes: - attribute_map: - direction: process.network.io.direction - apply_to_metrics: - - process.network.io - - rename_attributes: - attribute_map: - type: process.paging.faults.type - apply_to_metrics: - - process.paging.faults resources: changes: # https://github.com/open-telemetry/semantic-conventions/pull/178 From 7333624fcdf20de5a5bfa819349162ef0c5d2772 Mon Sep 17 00:00:00 2001 From: braydonk Date: Thu, 4 Jan 2024 16:39:17 +0000 Subject: [PATCH 07/13] in progress --- model/metrics/process-metrics.yaml | 26 +++++------------------ proposed_changelog.md | 16 +++++++++++++++ proposed_schema_next.yaml | 33 ++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 21 deletions(-) create mode 100644 proposed_changelog.md create mode 100644 proposed_schema_next.yaml diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 7ccc0f3549..3b141fd994 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -58,15 +58,7 @@ groups: instrument: counter unit: "By" attributes: - - id: process.disk.io_direction - brief: "The direction of the data transfer for this data point." - type: - allow_custom_values: true - members: - - id: read - value: 'read' - - id: write - value: 'write' + - ref: disk.io.direction - id: metric.process.network.io type: metric @@ -75,15 +67,7 @@ groups: instrument: counter unit: "By" attributes: - - id: process.network.io_direction - brief: "The direction of the data transfer for this data point." - type: - allow_custom_values: true - members: - - id: receive - value: 'receive' - - id: transmit - value: 'transmit' + - ref: network.io.direction - id: metric.process.thread.count type: metric @@ -95,7 +79,7 @@ groups: - id: metric.process.open_file_descriptor.count type: metric - metric_name: process.open_file_descriptors + metric_name: process.open_file_descriptor.count brief: "Number of file descriptors in use by the process." instrument: updowncounter unit: "{count}" @@ -108,7 +92,7 @@ groups: instrument: counter unit: "{count}" attributes: - - id: process.context_switch_type + - id: process.context_switches.type brief: "Specifies whether the context switches for this data point were voluntary or involuntary." type: allow_custom_values: true @@ -125,7 +109,7 @@ groups: instrument: counter unit: "{fault}" attributes: - - id: process.paging.fault_type + - id: process.paging.faults.type brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." type: allow_custom_values: true diff --git a/proposed_changelog.md b/proposed_changelog.md new file mode 100644 index 0000000000..0ae18248e3 --- /dev/null +++ b/proposed_changelog.md @@ -0,0 +1,16 @@ +- BREAKING: Generate process metrics from YAML + ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) + - Rename attributes for `process.cpu.*` + - `state` to `process.cpu.state` + - Change attributes for `process.disk.io` + - Instead of `direction` use the global `disk.io.direction` + - Change attributes for `process.network.io` + - Instead of `direction` use `network.io.direction` + - Rename `process.threads` to `process.thread.count` + - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` + - Rename `process.context_switches` to `process.context_switch.count` + - Rename attributes for `process.context_switch.count` + - `type` to `process.context_switch.type` + - Rename `process.paging.faults` to `process.paging.fault.count` + - Rename attributes for `process.paging.faults` + - `type` to `process.paging.fault.type` diff --git a/proposed_schema_next.yaml b/proposed_schema_next.yaml new file mode 100644 index 0000000000..750d705510 --- /dev/null +++ b/proposed_schema_next.yaml @@ -0,0 +1,33 @@ +metrics: +# https://github.com/open-telemetry/semantic-conventions/pull/330 +- rename_metrics: + process.threads: process.thread.count + process.open_file_descriptors: process.open_file_descriptor.count + process.context_switches: process.context_switch.count + process.paging.faults: process.paging.fault.count +- rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization +- rename_attributes: + attribute_map: + direction: disk.io.direction + apply_to_metrics: + - process.disk.io +- rename_attributes: + attribute_map: + type: process.context_switch.type + apply_to_metrics: + - process.context_switch.count +- rename_attributes: + attribute_map: + direction: network.io.direction + apply_to_metrics: + - process.network.io +- rename_attributes: + attribute_map: + type: process.paging.fault.type + apply_to_metrics: + - process.paging.fault.count \ No newline at end of file From d97169729eaec2836b5e1570d341faa678b64e42 Mon Sep 17 00:00:00 2001 From: braydonk Date: Wed, 10 Jan 2024 15:59:33 +0000 Subject: [PATCH 08/13] Use global refs to io direction attributes disk.io.direction and network.io.direction were added to the global registry, so this commit uses references to those attributes. --- docs/system/process-metrics.md | 36 +++++++++++++++--------------- model/metrics/process-metrics.yaml | 4 ++-- proposed_changelog.md | 14 ++++++------ proposed_schema_next.yaml | 8 +++---- 4 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 867899d0c6..6e330711b5 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -19,17 +19,17 @@ metrics](/docs/runtime/README.md#metrics). -- [Metric Instruments](#metric-instruments) - * [Metric: `process.cpu.time`](#metric-processcputime) - * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) - * [Metric: `process.memory.usage`](#metric-processmemoryusage) - * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) - * [Metric: `process.disk.io`](#metric-processdiskio) - * [Metric: `process.network.io`](#metric-processnetworkio) - * [Metric: `process.thread.count`](#metric-processthreadcount) - * [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) - * [Metric: `process.context_switches`](#metric-processcontext_switches) - * [Metric: `process.paging.faults`](#metric-processpagingfaults) +- [Process Metrics](#process-metrics) + - [Metric: `process.cpu.time`](#metric-processcputime) + - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + - [Metric: `process.memory.usage`](#metric-processmemoryusage) + - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + - [Metric: `process.disk.io`](#metric-processdiskio) + - [Metric: `process.network.io`](#metric-processnetworkio) + - [Metric: `process.thread.count`](#metric-processthreadcount) + - [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + - [Metric: `process.context_switches`](#metric-processcontext_switches) + - [Metric: `process.paging.faults`](#metric-processpagingfaults) @@ -43,7 +43,7 @@ metrics](/docs/runtime/README.md#metrics). > * SHOULD introduce a control mechanism to allow users to opt-in to the new > conventions once the migration plan is finalized. -## Metric Instruments +## Process Metrics ### Metric: `process.cpu.time` @@ -122,9 +122,9 @@ metrics](/docs/runtime/README.md#metrics). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `process.disk.process.disk.io_direction` | string | The direction of the data transfer for this data point. | `read` | Recommended | +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | -`process.disk.process.disk.io_direction` 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. +`disk.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -143,14 +143,14 @@ metrics](/docs/runtime/README.md#metrics). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `process.network.io_direction` | string | The direction of the data transfer for this data point. | `receive` | Recommended | +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | -`process.network.io_direction` 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. +`network.io.direction` MUST be one of the following: | Value | Description | |---|---| -| `receive` | receive | | `transmit` | transmit | +| `receive` | receive | ### Metric: `process.thread.count` @@ -169,7 +169,7 @@ metrics](/docs/runtime/README.md#metrics). | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.open_file_descriptors` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | +| `process.open_file_descriptor.count` | UpDownCounter | `{count}` | Number of file descriptors in use by the process. | diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 3b141fd994..cc663a9eaf 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -92,7 +92,7 @@ groups: instrument: counter unit: "{count}" attributes: - - id: process.context_switches.type + - id: process.context_switch_type brief: "Specifies whether the context switches for this data point were voluntary or involuntary." type: allow_custom_values: true @@ -109,7 +109,7 @@ groups: instrument: counter unit: "{fault}" attributes: - - id: process.paging.faults.type + - id: process.paging.fault_type brief: "The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults." type: allow_custom_values: true diff --git a/proposed_changelog.md b/proposed_changelog.md index 0ae18248e3..3c5b19ae13 100644 --- a/proposed_changelog.md +++ b/proposed_changelog.md @@ -1,16 +1,16 @@ +# Blah + - BREAKING: Generate process metrics from YAML ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - Rename attributes for `process.cpu.*` - `state` to `process.cpu.state` - Change attributes for `process.disk.io` - - Instead of `direction` use the global `disk.io.direction` + - Instead of `direction` use `disk.io.direction` from global registry - Change attributes for `process.network.io` - - Instead of `direction` use `network.io.direction` + - Instead of `direction` use `network.io.direction` from global registry - Rename `process.threads` to `process.thread.count` - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` - - Rename `process.context_switches` to `process.context_switch.count` - - Rename attributes for `process.context_switch.count` - - `type` to `process.context_switch.type` - - Rename `process.paging.faults` to `process.paging.fault.count` + - Rename attributes for `process.context_switches` + - `type` to `process.context_switch_type` - Rename attributes for `process.paging.faults` - - `type` to `process.paging.fault.type` + - `type` to `process.paging.fault_type` diff --git a/proposed_schema_next.yaml b/proposed_schema_next.yaml index 750d705510..b908e755f3 100644 --- a/proposed_schema_next.yaml +++ b/proposed_schema_next.yaml @@ -18,9 +18,9 @@ metrics: - process.disk.io - rename_attributes: attribute_map: - type: process.context_switch.type + type: process.context_switch_type apply_to_metrics: - - process.context_switch.count + - process.context_switches - rename_attributes: attribute_map: direction: network.io.direction @@ -28,6 +28,6 @@ metrics: - process.network.io - rename_attributes: attribute_map: - type: process.paging.fault.type + type: process.paging.fault_type apply_to_metrics: - - process.paging.fault.count \ No newline at end of file + - process.paging.faults \ No newline at end of file From 914e018823e3bcb85fc91eddb9b948ed4d13c2ea Mon Sep 17 00:00:00 2001 From: braydonk Date: Mon, 15 Jan 2024 14:52:18 +0000 Subject: [PATCH 09/13] Add recommended metric notices --- docs/system/process-metrics.md | 20 ++++++++++++++++++++ proposed_schema_next.yaml | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 6e330711b5..161b2209d2 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -47,6 +47,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.cpu.time` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -69,6 +71,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.cpu.utilization` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -91,6 +95,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.memory.usage` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -102,6 +108,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.memory.virtual` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -113,6 +121,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.disk.io` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -134,6 +144,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.network.io` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -155,6 +167,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.thread.count` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -166,6 +180,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.open_file_descriptor.count` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -177,6 +193,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.context_switches` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -198,6 +216,8 @@ metrics](/docs/runtime/README.md#metrics). ### Metric: `process.paging.faults` +This metric is [recommended][MetricRecommended]. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | diff --git a/proposed_schema_next.yaml b/proposed_schema_next.yaml index b908e755f3..3b8be52cc5 100644 --- a/proposed_schema_next.yaml +++ b/proposed_schema_next.yaml @@ -30,4 +30,4 @@ metrics: attribute_map: type: process.paging.fault_type apply_to_metrics: - - process.paging.faults \ No newline at end of file + - process.paging.faults From 0ecab73534dd4fe2c2fa1eebacc52aea1665ad18 Mon Sep 17 00:00:00 2001 From: braydonk Date: Mon, 15 Jan 2024 15:12:24 +0000 Subject: [PATCH 10/13] Forgot to define the MetricRecommended link --- docs/system/process-metrics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 161b2209d2..31b1367200 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -238,3 +238,4 @@ This metric is [recommended][MetricRecommended]. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended From f942cdbb5b6dcda7c2b83c09cbb008eb7855c59d Mon Sep 17 00:00:00 2001 From: braydonk Date: Thu, 18 Jan 2024 16:14:06 +0000 Subject: [PATCH 11/13] Add changelog and schema entries --- CHANGELOG.md | 14 ++++++++++++++ proposed_changelog.md | 16 ---------------- proposed_schema_next.yaml | 33 --------------------------------- schema-next.yaml | 33 +++++++++++++++++++++++++++++++++ 4 files changed, 47 insertions(+), 49 deletions(-) delete mode 100644 proposed_changelog.md delete mode 100644 proposed_schema_next.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dfe18a4a3..b2e6940d2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,20 @@ release. ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) - Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources ([#625](https://github.com/open-telemetry/semantic-conventions/pull/625)) +- BREAKING: Generate process metrics from YAML + ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) + - Rename `process.threads` to `process.thread.count` + - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` + - Rename attributes for `process.cpu.*` + - `state` to `process.cpu.state` + - Change attributes for `process.disk.io` + - Instead of `direction` use `disk.io.direction` from global registry + - Change attributes for `process.network.io` + - Instead of `direction` use `network.io.direction` from global registry + - Rename attributes for `process.context_switches` + - `type` to `process.context_switch_type` + - Rename attributes for `process.paging.faults` + - `type` to `process.paging.fault_type` ### Features diff --git a/proposed_changelog.md b/proposed_changelog.md deleted file mode 100644 index 3c5b19ae13..0000000000 --- a/proposed_changelog.md +++ /dev/null @@ -1,16 +0,0 @@ -# Blah - -- BREAKING: Generate process metrics from YAML - ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - - Rename attributes for `process.cpu.*` - - `state` to `process.cpu.state` - - Change attributes for `process.disk.io` - - Instead of `direction` use `disk.io.direction` from global registry - - Change attributes for `process.network.io` - - Instead of `direction` use `network.io.direction` from global registry - - Rename `process.threads` to `process.thread.count` - - Rename `process.open_file_descriptors` to `process.open_file_descriptor.count` - - Rename attributes for `process.context_switches` - - `type` to `process.context_switch_type` - - Rename attributes for `process.paging.faults` - - `type` to `process.paging.fault_type` diff --git a/proposed_schema_next.yaml b/proposed_schema_next.yaml deleted file mode 100644 index 3b8be52cc5..0000000000 --- a/proposed_schema_next.yaml +++ /dev/null @@ -1,33 +0,0 @@ -metrics: -# https://github.com/open-telemetry/semantic-conventions/pull/330 -- rename_metrics: - process.threads: process.thread.count - process.open_file_descriptors: process.open_file_descriptor.count - process.context_switches: process.context_switch.count - process.paging.faults: process.paging.fault.count -- rename_attributes: - attribute_map: - state: process.cpu.state - apply_to_metrics: - - process.cpu.time - - process.cpu.utilization -- rename_attributes: - attribute_map: - direction: disk.io.direction - apply_to_metrics: - - process.disk.io -- rename_attributes: - attribute_map: - type: process.context_switch_type - apply_to_metrics: - - process.context_switches -- rename_attributes: - attribute_map: - direction: network.io.direction - apply_to_metrics: - - process.network.io -- rename_attributes: - attribute_map: - type: process.paging.fault_type - apply_to_metrics: - - process.paging.faults diff --git a/schema-next.yaml b/schema-next.yaml index 58de42a543..46b6092e56 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -18,6 +18,39 @@ versions: attribute_map: container.labels: container.label k8s.pod.labels: k8s.pod.label + # https://github.com/open-telemetry/semantic-conventions/pull/330 + - rename_metrics: + process.threads: process.thread.count + process.open_file_descriptors: process.open_file_descriptor.count + process.context_switches: process.context_switch.count + process.paging.faults: process.paging.fault.count + - rename_attributes: + attribute_map: + state: process.cpu.state + apply_to_metrics: + - process.cpu.time + - process.cpu.utilization + - rename_attributes: + attribute_map: + direction: disk.io.direction + apply_to_metrics: + - process.disk.io + - rename_attributes: + attribute_map: + type: process.context_switch_type + apply_to_metrics: + - process.context_switches + - rename_attributes: + attribute_map: + direction: network.io.direction + apply_to_metrics: + - process.network.io + - rename_attributes: + attribute_map: + type: process.paging.fault_type + apply_to_metrics: + - process.paging.faults + 1.24.0: metrics: changes: From d5f31bac428a07e056d70c0b27419fdf091b79b2 Mon Sep 17 00:00:00 2001 From: braydonk Date: Thu, 18 Jan 2024 16:16:13 +0000 Subject: [PATCH 12/13] generate table of contents --- docs/system/process-metrics.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 31b1367200..35e343349e 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -20,16 +20,16 @@ metrics](/docs/runtime/README.md#metrics). - [Process Metrics](#process-metrics) - - [Metric: `process.cpu.time`](#metric-processcputime) - - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) - - [Metric: `process.memory.usage`](#metric-processmemoryusage) - - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) - - [Metric: `process.disk.io`](#metric-processdiskio) - - [Metric: `process.network.io`](#metric-processnetworkio) - - [Metric: `process.thread.count`](#metric-processthreadcount) - - [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) - - [Metric: `process.context_switches`](#metric-processcontext_switches) - - [Metric: `process.paging.faults`](#metric-processpagingfaults) + * [Metric: `process.cpu.time`](#metric-processcputime) + * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + * [Metric: `process.memory.usage`](#metric-processmemoryusage) + * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + * [Metric: `process.disk.io`](#metric-processdiskio) + * [Metric: `process.network.io`](#metric-processnetworkio) + * [Metric: `process.thread.count`](#metric-processthreadcount) + * [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + * [Metric: `process.context_switches`](#metric-processcontext_switches) + * [Metric: `process.paging.faults`](#metric-processpagingfaults) From 05f6cd3862d4595d0a8a7d569cdb42daec519cc2 Mon Sep 17 00:00:00 2001 From: braydonk Date: Thu, 18 Jan 2024 18:17:35 +0000 Subject: [PATCH 13/13] fix bad schema entry that was left in by accident --- schema-next.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/schema-next.yaml b/schema-next.yaml index 46b6092e56..23ebad9a35 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -22,8 +22,6 @@ versions: - rename_metrics: process.threads: process.thread.count process.open_file_descriptors: process.open_file_descriptor.count - process.context_switches: process.context_switch.count - process.paging.faults: process.paging.fault.count - rename_attributes: attribute_map: state: process.cpu.state