From 7e35bec9401d9bc970a7107af45906c0890040b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20St=C3=A4ber?= Date: Fri, 8 Apr 2022 20:14:29 +0200 Subject: [PATCH] Allow all metric conventions to be either synchronous or asynchronous. (#2458) --- CHANGELOG.md | 2 + .../metrics/semantic_conventions/README.md | 9 ++ .../semantic_conventions/faas-metrics.md | 38 +++--- .../semantic_conventions/http-metrics.md | 58 ++++----- .../semantic_conventions/process-metrics.md | 14 +-- .../metrics/semantic_conventions/rpc.md | 4 +- .../runtime-environment-metrics.md | 20 +-- .../semantic_conventions/system-metrics.md | 119 +++++++++--------- 8 files changed, 140 insertions(+), 124 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70efdaaed94..2cded699afc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -121,6 +121,8 @@ release. ([#2290](https://github.com/open-telemetry/opentelemetry-specification/pull/2290)) - Add semantic conventions for [CloudEvents](https://cloudevents.io). ([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978)) +- Allow all metric conventions to be either synchronous or asynchronous. + ([#2458](https://github.com/open-telemetry/opentelemetry-specification/pull/2458) - Add `process.cpu.utilization` metric. ([#2436](https://github.com/open-telemetry/opentelemetry-specification/pull/2436)) - Add `rpc.system` value for Apache Dubbo. diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index d3532815d42..eb02009d4bb 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -13,6 +13,7 @@ - [General Metric Semantic Conventions](#general-metric-semantic-conventions) * [Instrument Naming](#instrument-naming) * [Instrument Units](#instrument-units) + * [Instrument Types](#instrument-types) @@ -165,3 +166,11 @@ total) are dimensionless and SHOULD use the default unit `1` (the unity). [annotations](https://ucum.org/ucum.html#para-curly) with curly braces to give additional meaning *without* the leading default unit (`1`). For example, use `{packets}`, `{errors}`, `{faults}`, etc. + +### Instrument Types + +The semantic metric conventions specification is written to use the names of the synchronous instrument types, +like `Counter` or `UpDownCounter`. However, compliant implementations MAY use the asynchronous equivalent instead, +like `Asynchronous Counter` or `Asynchronous UpDownCounter`. +Whether implementations choose the synchronous type or the asynchronous equivalent is considered to be an +implementation detail. Both choices are compliant with this specification. diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md index 67dcf534e2e..45d2bdc6225 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -32,33 +32,33 @@ type and units. Below is a table of FaaS invocation metric instruments. -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------|------------|------|-------------------------------------------|-------------| -| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | -| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | -| `faas.coldstarts` | Counter | default unit | `{coldstarts}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{errors}` | Number of invocation errors. | -| `faas.executions` | Counter | default unit | `{executions}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| +| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | +| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | +| `faas.coldstarts` | Counter | default unit | `{coldstarts}` | Number of invocation cold starts. | +| `faas.errors` | Counter | default unit | `{errors}` | Number of invocation errors. | +| `faas.executions` | Counter | default unit | `{executions}` | Number of successful invocations. | +| `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. | Optionally, when applicable: -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------|------------|------|-------------------------------------------|-------------| -| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | -| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of cpu usage per invocation | -| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| +| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | +| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of cpu usage per invocation | +| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | ## Attributes Below is a table of the attributes to be included on FaaS metric events. -| Name | Recommended | Notes and examples | -|------|-------------|--------------------| -| `faas.trigger` | Yes | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | -| `faas.invoked_name` | Yes | Name of the invoked function. Example: `my-function` | -| `faas.invoked_provider` | Yes | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | -| `faas.invoked_region` | Yes | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | +| Name | Recommended | Notes and examples | +|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------| +| `faas.trigger` | Yes | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | +| `faas.invoked_name` | Yes | Name of the invoked function. Example: `my-function` | +| `faas.invoked_provider` | Yes | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | +| `faas.invoked_region` | Yes | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md). For incoming FaaS executions, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md). diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 204ef410ab0..3a72cb02d00 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -17,46 +17,46 @@ type and units. Below is a table of HTTP server metric instruments. -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|-------------------------------|----------------------------|--------------|-------------------------------------------|-------------| -| `http.server.duration` | Histogram | milliseconds | `ms` | measures the duration of the inbound HTTP request | -| `http.server.active_requests` | Asynchronous UpDownCounter | requests | `{requests}` | measures the number of concurrent HTTP requests that are currently in-flight | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|-------------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| +| `http.server.duration` | Histogram | milliseconds | `ms` | measures the duration of the inbound HTTP request | +| `http.server.active_requests` | UpDownCounter | requests | `{requests}` | measures the number of concurrent HTTP requests that are currently in-flight | ### HTTP Client Below is a table of HTTP client metric instruments. -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------------------------|------------|--------------|-------------------------------------------|-------------| -| `http.client.duration` | Histogram | milliseconds | `ms` | measures the duration of the outbound HTTP request | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | +|------------------------|---------------------------------------------------|--------------|-------------------------------------------|----------------------------------------------------| +| `http.client.duration` | Histogram | milliseconds | `ms` | measures the duration of the outbound HTTP request | ## Attributes Below is a table of the attributes that SHOULD be included on `duration` metric events and whether they should be on server, client, or both types of HTTP metric events: -| Name | Type | Recommended | Notes and examples | -|--------------------|---------------------|-------------------|--------------------| -| `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | -| `http.host` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | -| `http.scheme` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | -| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (String) | -| `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.peer.port` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.peer.ip` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| Name | Type | Recommended | Notes and examples | +|--------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | +| `http.host` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | +| `http.scheme` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | +| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (String) | +| `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | +| `net.peer.name` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.peer.port` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.peer.ip` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | | `http.server_name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | -| `net.host.name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.host.port` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.port` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | The following attributes SHOULD be included in the `http.server.active_requests` observation: -| Name | Recommended | Notes and examples | -|--------------------|-------------|--------------------| -| `http.method` | Yes | The HTTP request method. E.g. `"GET"` | -| `http.host` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same | -| `http.scheme` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | -| `http.flavor` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` | +| Name | Recommended | Notes and examples | +|--------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `http.method` | Yes | The HTTP request method. E.g. `"GET"` | +| `http.host` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same | +| `http.scheme` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | +| `http.flavor` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` | | `http.server_name` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 @@ -67,10 +67,10 @@ The following attributes SHOULD be included in the `http.server.active_requests` To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below: -| Attribute name | Type | Recommended | Notes and examples | -|-------------------|---------------------|-------------|---------------------| -|`http.url` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The originally requested URL | -|`http.target` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | +| Attribute name | Type | Recommended | Notes and examples | +|----------------|---------------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| `http.url` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The originally requested URL | +| `http.target` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | [HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 diff --git a/specification/metrics/semantic_conventions/process-metrics.md b/specification/metrics/semantic_conventions/process-metrics.md index d51651de9db..2358c16aca3 100644 --- a/specification/metrics/semantic_conventions/process-metrics.md +++ b/specification/metrics/semantic_conventions/process-metrics.md @@ -27,13 +27,13 @@ metrics](runtime-environment-metrics.md). Below is a table of Process metric instruments. -| Name | Instrument | Units | Description | Labels | -|------|------------|-------|-------------|--------| -| `process.cpu.time` | Asynchronous 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` | Asynchronous Gauge | s | 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` | Asynchronous UpDownCounter | By | The amount of physical memory in use. | | -| `process.memory.virtual` | Asynchronous UpDownCounter | By | The amount of committed virtual memory. | | -| `process.disk.io` | Asynchronous Counter | By | Disk bytes transferred. | `direction` SHOULD be one of: `read`, `write` | +| Name | Instrument Type ([*](README.md#instrument-types)) | Units | 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 | s | 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` | ## Attributes diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index f23ca38b7cf..85b29abf693 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -31,7 +31,7 @@ MUST be of the specified type and units. Below is a table of RPC server metric instruments. -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | @@ -44,7 +44,7 @@ Below is a table of RPC server metric instruments. Below is a table of RPC client metric instruments. These apply to traditional RPC usage, not streaming RPCs. -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index bd07f0b1655..f4125337e16 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -57,16 +57,16 @@ consider, for example pthreads vs green thread implementations. All JVM metric attributes are required unless otherwise indicated. -| Name | Description | Unit | Unit ([UCUM](README.md#instrument-units)) | Instrument Type | Value Type | Attribute Key | Attribute Values | -|--------------------------------------|-------------------------------------|-------|-------------------------------------------|----------------------------|------------|---------------|-----------------------| -| process.runtime.jvm.memory.usage | Measure of memory used | Bytes | `By` | Asynchronous UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.init | Measure of initial memory requested | Bytes | `By` | Asynchronous UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.committed | Measure of memory committed | Bytes | `By` | Asynchronous UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.max | Measure of max obtainable memory | Bytes | `By` | Asynchronous UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | -| | | | | | | pool | Name of pool [1] | +| Name | Description | Unit | Unit ([UCUM](README.md#instrument-units)) | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +|--------------------------------------|-------------------------------------|-------|-------------------------------------------|---------------------------------------------------|------------|---------------|-----------------------| +| process.runtime.jvm.memory.usage | Measure of memory used | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | +| | | | | | | pool | Name of pool [1] | +| process.runtime.jvm.memory.init | Measure of initial memory requested | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | +| | | | | | | pool | Name of pool [1] | +| process.runtime.jvm.memory.committed | Measure of memory committed | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | +| | | | | | | pool | Name of pool [1] | +| process.runtime.jvm.memory.max | Measure of max obtainable memory | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"nonheap"` | +| | | | | | | pool | Name of pool [1] | **[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()) diff --git a/specification/metrics/semantic_conventions/system-metrics.md b/specification/metrics/semantic_conventions/system-metrics.md index 04e83f212f2..9a5b23badc8 100644 --- a/specification/metrics/semantic_conventions/system-metrics.md +++ b/specification/metrics/semantic_conventions/system-metrics.md @@ -29,48 +29,50 @@ instruments not explicitly defined in the specification. **Description:** System level processor metrics. -| Name | Description | Units | Instrument Type | Value Type | Attribute Key(s) | Attribute Values | -| ---------------------- | ----------- | ----- | ---------------------| ---------- | ---------------- | ----------------------------------- | -| system.cpu.time | | s | Asynchronous Counter | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | 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 CPUs | 1 | Asynchronous Gauge | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number (0..n) | +| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +|------------------------|----------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------|------------|------------------|-------------------------------------| +| system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | +| | | | | | cpu | 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 CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | +| | | | | | cpu | CPU number (0..n) | ### `system.memory.` - Memory metrics **Description:** System level memory metrics. This does not include [paging/swap memory](#systempaging---pagingswap-metrics). -| Name | Description | Units | Instrument Type | Value Type | Attribute Key | Attribute Values | -| ------------------------- | ----------- | ----- | ----------------- | ---------- | ------------- | ------------------------ | -| system.memory.usage | | By | Asynchronous UpDownCounter | Int64 | state | used, free, cached, etc. | -| system.memory.utilization | | 1 | Asynchronous Gauge | Double | state | used, free, cached, etc. | +| Name | Description | Units | Instrument Type ([*](README.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 | Value Type | Attribute Key | Attribute Values | -| ------------------------- | ----------------------------------- | ------------ | -------------------------- | ---------- | ------------- | ---------------- | -| system.paging.usage | Unix swap or windows pagefile usage | By | Asynchronous UpDownCounter | Int64 | state | used, free | -| system.paging.utilization | | 1 | Asynchronous Gauge | Double | state | used, free | -| system.paging.faults | | {faults} | Asynchronous Counter | Int64 | type | major, minor | -| system.paging.operations | | {operations} | Asynchronous Counter | Int64 | type | major, minor | -| | | | | | direction | in, out | + +| Name | Description | Units | Instrument Type ([*](README.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 | | {faults} | Counter | Int64 | type | major, minor | +| system.paging.operations | | {operations} | Counter | Int64 | type | major, minor | +| | | | | | direction | in, out | ### `system.disk.` - Disk controller metrics **Description:** System level disk performance metrics. -| Name | Description | Units | Instrument Type | Value Type | Attribute Key | Attribute Values | -| --------------------------------------------------------- | ----------------------------------------------- | ------------ | ------------------------ | ---------- | ------------- | ---------------- | -| system.disk.io | | By | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.operations | | {operations} | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.io_time\[1\] | Time disk spent activated | s | Asynchronous Counter | Double | device | (identifier) | -| system.disk.operation_time\[2\] | Sum of the time each operation took to complete | s | Asynchronous Counter | Double | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.merged | | {operations} | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | + +| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +|--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| +| system.disk.io | | By | Counter | Int64 | device | (identifier) | +| | | | | | direction | read, write | +| system.disk.operations | | {operations} | 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 | | {operations} | 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 @@ -94,35 +96,37 @@ perf counter (similar for Writes) ### `system.filesystem.` - Filesystem metrics **Description:** System level filesystem metrics. -| Name | Description | Units | Instrument Type | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------- | ----- | -------------------------- | ---------- | -------------- | -------------------- | -| system.filesystem.usage | | By | Asynchronous UpDownCounter | Int64 | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | -| system.filesystem.utilization | | 1 | Asynchronous Gauge | Double | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | + +| Name | Description | Units | Instrument Type ([*](README.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. | +| | | | | | mountain | (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 | Value Type | Attribute Key | Attribute Values | -| ---------------------------------------------- | ----------------------------------------------------------------------------- | ------------- | -------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packets} | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.packets | | {packets} | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.errors\[2\] | Count of network errors detected | {errors} | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.io | | By | Asynchronous Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.connections | | {connections} | Asynchronous UpDownCounter | Int64 | device | (identifier) | -| | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | -| | | | | | state | [e.g. for tcp](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Protocol_operation) | + +| Name | Description | Units | Instrument Type ([*](README.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 | {packets} | Counter | Int64 | device | (identifier) | +| | | | | | direction | transmit, receive | +| system.network.packets | | {packets} | Counter | Int64 | device | (identifier) | +| | | | | | direction | transmit, receive | +| system.network.errors\[2\] | Count of network errors detected | {errors} | Counter | Int64 | device | (identifier) | +| | | | | | direction | transmit, receive | +| system.network.io | | By | Counter | Int64 | device | (identifier) | +| | | | | | direction | transmit, receive | +| system.network.connections | | {connections} | UpDownCounter | Int64 | device | (identifier) | +| | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | +| | | | | | state | [e.g. for tcp](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Protocol_operation) | 1 Measured as: @@ -146,10 +150,11 @@ from **Description:** System level aggregate process metrics. For metrics at the individual process level, see [process metrics](process-metrics.md). -| Name | Description | Units | Instrument Type | Value Type | Attribute Key | Attribute Values | -| ------------------------ | --------------------------------------------------------- | ----------- | -------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.processes.count | Total number of processes in each state | {processes} | Asynchronous 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 | {processes} | Asynchronous Counter | Int64 | - | - | + +| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +|--------------------------|-----------------------------------------------------------|-------------|---------------------------------------------------|------------|---------------|------------------------------------------------------------------------------------------------| +| system.processes.count | Total number of processes in each state | {processes} | 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 | {processes} | Counter | Int64 | - | - | ### `system.{os}.` - OS Specific System Metrics