Skip to content

use seconds for all durations as specified for durations #176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
zeitlinger wants to merge 2 commits into from
Closed

use seconds for all durations as specified for durations #176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e53ae2
use seconds for all durations as specified for durations
zeitlinger Jul 7, 2023
b711d2d
use explicit bucket boundaries for all seconds histograms
zeitlinger Jul 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions docs/database/database-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
24 changes: 13 additions & 11 deletions docs/faas/faas-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Copy link
Member

@jack-berg jack-berg Jul 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't these changes come with explicit bucket boundary advice so that the distribution is useful out of the box?

This question applies to all the histogram metrics that appear in this PR.

Copy link
Member Author

@zeitlinger zeitlinger Jul 11, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch - added

| `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

Expand Down
7 changes: 7 additions & 0 deletions docs/general/metrics-general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -202,6 +203,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]
Expand Down
4 changes: 1 addition & 3 deletions docs/http/http-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<!-- semconv metric.http.server.duration(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
Expand Down
12 changes: 8 additions & 4 deletions docs/rpc/rpc-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 |
Expand Down
2 changes: 2 additions & 0 deletions docs/system/runtime-environment-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<!-- semconv metric.process.runtime.jvm.gc.duration(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
Expand Down