Skip to content
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.

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

Metric requirement levels #3237

Merged
merged 11 commits into from
Feb 23, 2023
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ release.

### Metrics

- Add metric requirement levels "Required", "Recommended", and "Opt-In".
([#3237](https://github.com/open-telemetry/opentelemetry-specification/pull/3237))

### Logs

- Rename Logs API to Logs Bridge API to prevent confusion.
Expand Down
36 changes: 36 additions & 0 deletions specification/metrics/metric-requirement-level.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Metric Requirement Levels for Semantic Conventions
trask marked this conversation as resolved.
Show resolved Hide resolved

**Status**: [Experimental](../document-status.md)

<details>
<summary>Table of Contents</summary>

<!-- toc -->

- [Required](#required)
- [Recommended](#recommended)
- [Opt-In](#opt-in)

<!-- tocstop -->

</details>

The following metric requirement levels are specified:

- [Required](#required)
- [Recommended](#recommended)
- [Opt-In](#opt-in)

## Required

All instrumentations MUST emit the metric. A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it. `http.server.duration` is an example of a Required metric.
trask marked this conversation as resolved.
Show resolved Hide resolved

## Recommended

Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics.

Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD use the `Opt-In` requirement level on them if the metrics are logically applicable.
trask marked this conversation as resolved.
Show resolved Hide resolved

## Opt-In

Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics.
trask marked this conversation as resolved.
Show resolved Hide resolved