From 9e53ae25a1e243118730f52dc3ec469d4a73425b Mon Sep 17 00:00:00 2001 From: gregor Date: Fri, 7 Jul 2023 13:12:10 +0200 Subject: [PATCH 1/2] use seconds for all durations as specified for durations --- docs/database/database-metrics.md | 20 ++++++++++-------- docs/faas/faas-metrics.md | 24 ++++++++++++---------- docs/general/metrics-general.md | 6 ++++++ docs/http/http-metrics.md | 4 +--- docs/rpc/rpc-metrics.md | 12 +++++++---- docs/system/runtime-environment-metrics.md | 2 ++ 6 files changed, 41 insertions(+), 27 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 1387be5792..38a96e08b1 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -39,20 +39,22 @@ All `db.client.connections.usage` measurements MUST include the following attrib |---------|--------|------------------------------------------------------------------------------|----------|-------------------| | `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required | +All duration metrics SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). + Instrumentation libraries for database client connection pools that collect data for the following data MUST use the following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments MUST NOT be used. | Name | Instrument ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | -|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| -| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | -| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | -| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | -| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | -| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | -| `db.client.connections.create_time` | Histogram | milliseconds | `ms` | The time it took to create a new connection. | -| `db.client.connections.wait_time` | Histogram | milliseconds | `ms` | The time it took to obtain an open connection from the pool. | -| `db.client.connections.use_time` | Histogram | milliseconds | `ms` | The time between borrowing a connection and returning it to the pool. | +|------------------------------------------|----------------------------------------------|--------------|----------------------------------------|---------------------------------------------------------------------------------------------------| +| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | +| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | +| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | +| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | +| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | +| `db.client.connections.create_time` | Histogram | seconds | `s` | The time it took to create a new connection. | +| `db.client.connections.wait_time` | Histogram | seconds | `s` | The time it took to obtain an open connection from the pool. | +| `db.client.connections.use_time` | Histogram | seconds | `s` | The time between borrowing a connection and returning it to the pool. | Below is a table of the attributes that MUST be included on all connection pool measurements: diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 4ec721ded0..218f28094e 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -36,22 +36,24 @@ type and units. Below is a table of FaaS invocation metric instruments. +All duration metrics SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). + | Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.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 | `{coldstart}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | +|------------------------|---------------------------------------------------|--------------|-----------------------------------------|------------------------------------------------------------------------------| +| `faas.invoke_duration` | Histogram | seconds | `s` | Measures the duration of the invocation | +| `faas.init_duration` | Histogram | seconds | `s` | Measures the duration of the function's initialization, such as a cold start | +| `faas.coldstarts` | Counter | default unit | `{coldstart}` | Number of invocation cold starts. | +| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | +| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | +| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | Optionally, when applicable: | Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.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 | +|------------------|---------------------------------------------------|--------------|------------------------------------------|-------------------------------------------------| +| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | +| `faas.cpu_usage` | Histogram | seconds | `s` | Distribution of CPU usage per invocation | +| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | ## Attributes diff --git a/docs/general/metrics-general.md b/docs/general/metrics-general.md index 9c92afdaf4..c89b8f50c3 100644 --- a/docs/general/metrics-general.md +++ b/docs/general/metrics-general.md @@ -202,6 +202,12 @@ use `{packet}`, `{error}`, `{fault}`, etc. unless there is good technical reason to not do so. - When instruments are measuring durations, seconds (i.e. `s`) SHOULD be used. +#### Explicit Bucket boundaries for Duration Histograms + +Duration histograms SHOULD use seconds (see above) and SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. + ### Instrument Types **Status**: [Stable][DocumentStatus] diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 77b062b48b..3b6b98dd85 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -61,9 +61,7 @@ This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) -of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. +This metric SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). | Name | Instrument Type | Unit (UCUM) | Description | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 49e067bbba..e176abf01e 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,9 +61,11 @@ MUST be of the specified type and units. Below is a table of RPC server metric instruments. +All duration metrics SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). + | Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.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.duration` | Histogram | seconds | `s` | 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 | | `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch | | `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | @@ -74,9 +76,11 @@ 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. +All duration metrics SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). + | Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.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.duration` | Histogram | seconds | `s` | 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 | | `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch | | `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index d28c355e90..6a656bf1bc 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -195,6 +195,8 @@ This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) of `[]` (single bucket histogram capturing count, sum, min, max). +This metric SHOULD use [`ExplicitBucketBoundaries`](../general/metrics-general.md#explicit-bucket-boundaries-for-duration-histograms). + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | From b711d2d25e9d1a4231e2095f713f7b0e8191b30f Mon Sep 17 00:00:00 2001 From: gregor Date: Tue, 11 Jul 2023 10:34:13 +0200 Subject: [PATCH 2/2] use explicit bucket boundaries for all seconds histograms --- docs/general/metrics-general.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/general/metrics-general.md b/docs/general/metrics-general.md index c89b8f50c3..5ce5810f11 100644 --- a/docs/general/metrics-general.md +++ b/docs/general/metrics-general.md @@ -16,6 +16,7 @@ linkTitle: Metrics - [General Metric Semantic Conventions](#general-metric-semantic-conventions) * [Instrument Naming](#instrument-naming) * [Instrument Units](#instrument-units) + + [Explicit Bucket boundaries for Duration Histograms](#explicit-bucket-boundaries-for-duration-histograms) * [Instrument Types](#instrument-types) * [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)