Skip to content

Commit

Permalink
Fix grammatical number of metric semconv units (open-telemetry#3298)
Browse files Browse the repository at this point in the history
  • Loading branch information
@MrAlias @lmolkova
MrAlias authored and lmolkova committed Mar 8, 2023
1 parent d17c016 commit 7208924
Show file tree
Hide file tree
Showing 11 changed files with 67 additions and 61 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ release.

### Semantic Conventions

- Fix grammatical number of metric units.
([#3298](https://github.com/open-telemetry/opentelemetry-specification/pull/3298))
- BREAKING: rename `http.client_ip` to `http.forwarded.for` and introduce `http.forwarded.proto` attributes.
([#3218](https://github.com/open-telemetry/opentelemetry-specification/pull/3218))

Expand Down
2 changes: 1 addition & 1 deletion semantic_conventions/metrics/http.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ groups:
metric_name: http.server.active_requests
brief: "Measures the number of concurrent HTTP requests that are currently in-flight."
instrument: updowncounter
unit: "{requests}"
unit: "{request}"
attributes:
- ref: http.method
- ref: http.status_code
Expand Down
8 changes: 6 additions & 2 deletions specification/metrics/semantic_conventions/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
[countable quantity](https://en.wikipedia.org/wiki/Count_noun).
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a non-unit (like `{faults}` or `{operations}`).
question is a non-unit (like `{fault}` or `{operation}`).

Examples:

Expand Down Expand Up @@ -180,10 +180,14 @@ more clarification in

- Instruments for **utilization** metrics (that measure the fraction out of a
total) are dimensionless and SHOULD use the default unit `1` (the unity).
- All non-units that use curly braces to annotate a quantity need to match the
grammatical number of the quantity it represent. For example if measuring the
number of individual requests to a process the unit would be `{request}`, not
`{requests}`.
- Instruments that measure an integer count of something SHOULD only use
[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.
use `{packet}`, `{error}`, `{fault}`, etc.

### Instrument Types

Expand Down
12 changes: 6 additions & 6 deletions specification/metrics/semantic_conventions/database-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ instrumentations:

| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------|
| `db.client.connections.usage` | UpDownCounter | connections | `{connections}` | The number of connections that are currently in state described by the `state` attribute. |
| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. |

All `db.client.connections.usage` measurements MUST include the following attribute:

Expand All @@ -45,11 +45,11 @@ MUST NOT be used.

| Name | Instrument ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------|
| `db.client.connections.idle.max` | UpDownCounter | connections | `{connections}` | The maximum number of idle open connections allowed. |
| `db.client.connections.idle.min` | UpDownCounter | connections | `{connections}` | The minimum number of idle open connections allowed. |
| `db.client.connections.max` | UpDownCounter | connections | `{connections}` | The maximum number of open connections allowed. |
| `db.client.connections.pending_requests` | UpDownCounter | requests | `{requests}` | The number of pending requests for an open connection, cumulative for the entire pool. |
| `db.client.connections.timeouts` | Counter | timeouts | `{timeouts}` | The number of connection timeouts that have occurred trying to obtain a connection from 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 | 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. |
Expand Down
8 changes: 4 additions & 4 deletions specification/metrics/semantic_conventions/faas-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ Below is a table of FaaS invocation metric instruments.
|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------|
| `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.invocations` | Counter | default unit | `{invocations}` | Number of successful invocations. |
| `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. |
| `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:

Expand Down
Loading

0 comments on commit 7208924

Please sign in to comment.