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.

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

[docs] Tweaks for stable metric point reclaim #5957

Merged
merged 1 commit into from
Nov 8, 2024
Merged

[docs] Tweaks for stable metric point reclaim #5957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 6 additions & 0 deletions RELEASENOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,12 @@ directory of each individual package.
variable is no longer required. For details see: [Cardinality
Limits](./docs/metrics/README.md#cardinality-limits).

* The MetricPoint reclaim behavior is now enabled by default when Delta
aggregation temporality is used. The
`OTEL_DOTNET_EXPERIMENTAL_METRICS_RECLAIM_UNUSED_METRIC_POINTS` environment
variable is no longer required. For details see: [Cardinality
Limits](./docs/metrics/README.md#cardinality-limits).

* Added `OpenTelemetrySdk.Create` API for configuring OpenTelemetry .NET signals
(logging, tracing, and metrics) via a single builder. This new API simplifies
bootstrap and teardown, and supports cross-cutting extensions targeting
Expand Down
29 changes: 15 additions & 14 deletions docs/metrics/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,23 +388,24 @@ and the `MetricStreamConfiguration.CardinalityLimit` setting. Refer to this
[doc](../../docs/metrics/customizing-the-sdk/README.md#changing-the-cardinality-limit-for-a-metric)
for more information.

Given a metric, once the cardinality limit is reached, any new measurement
that could not be independently aggregated will be aggregated using the
[overflow attribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#overflow-attribute).
In versions prior to 1.10.0, the default behavior when cardinality limit was
reached was to drop the measurement. Users had the ability to opt-in to use
overflow attribute instead, but this behavior is the default and the only
allowed behavior starting with version 1.10.0.

When [Delta Aggregation
As of `1.10.0` once a metric has reached the cardinality limit, any new
measurement that could not be independently aggregated will be automatically
aggregated using the [overflow
attribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#overflow-attribute).

> [!NOTE]
> In SDK versions `1.6.0` - `1.9.0` the overflow attribute was an experimental
feature that could be enabled by setting the environment variable
`OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE=true`.

As of `1.10.0` when [Delta Aggregation
Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#temporality)
is used, it is possible to choose a smaller cardinality limit by allowing the
SDK to reclaim unused metric points.
is used, it is possible to choose a smaller cardinality limit because the SDK
will reclaim unused metric points.

> [!NOTE]
> Metric points reclaim is the default and only behavior for Delta Aggregation
Temporality starting with version 1.10.0. In version 1.7.0 - 1.9.0, it was an
experimental feature that could be enabled by setting the environment variable
> In SDK versions `1.7.0` - `1.9.0`, metric point reclaim was an experimental
feature that could be enabled by setting the environment variable
`OTEL_DOTNET_EXPERIMENTAL_METRICS_RECLAIM_UNUSED_METRIC_POINTS=true`.

### Memory Preallocation
Expand Down
38 changes: 22 additions & 16 deletions src/OpenTelemetry/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,22 @@ Notes](../../RELEASENOTES.md).

## Unreleased

* Promote MetricPoint reclaim feature for delta aggregation from experimental to
stable.
Previously, it is an experimental feature which can be turned on by setting
the environment variable
`OTEL_DOTNET_EXPERIMENTAL_METRICS_RECLAIM_UNUSED_METRIC_POINTS=true`.
Now that the [OpenTelemetry
Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#overflow-attribute)
has become stable. The feature is the default and the only allowed behavior
without the need to set an environment variable.
* Promoted the MetricPoint reclaim feature for Delta aggregation temporality
from experimental to stable.
([#5956](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5956))

**Previous Behavior:**
The SDK maintained a fixed set of MetricPoints which were assigned on a
first-come basis based on the tags. MetricPoint reclaim was an experimental
feature users could opt-into setting the environment variable
`OTEL_DOTNET_EXPERIMENTAL_METRICS_RECLAIM_UNUSED_METRIC_POINTS=true`.

**New Behavior:**
MetricPoint reclaim is now enabled by default when Delta aggregation
temporality is used without the need to set an environment variable. Unused
MetricPoints will automatically be reclaimed and reused for future
measurements. There is NO ability to revert to the old behavior.

## 1.10.0-rc.1

Released 2024-Nov-01
Expand All @@ -27,16 +32,18 @@ Released 2024-Nov-01
([#5926](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5926))

* Promoted overflow attribute from experimental to stable and removed the
`OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE` environment variable.
`OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE` environment
variable.
([#5909](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5909))

**Previous Behavior:**
By default, when the cardinality limit was reached, measurements were dropped,
and an internal log was emitted the first time this occurred. Users could
opt-in to experimental overflow attribute feature with
`OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE=true`.
With this setting, the SDK would use an overflow attribute
(`otel.metric.overflow = true`) to aggregate measurements instead of dropping
measurements. No internal log was emitted in this case.
opt-into experimental overflow attribute feature with
`OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE=true`. With this
setting, the SDK would use an overflow attribute (`otel.metric.overflow =
true`) to aggregate measurements instead of dropping measurements. No internal
log was emitted in this case.

**New Behavior:**
The SDK now always uses the overflow attribute (`otel.metric.overflow = true`)
Expand All @@ -49,7 +56,6 @@ Released 2024-Nov-01
Metric](../../docs/metrics/customizing-the-sdk/README.md#changing-the-cardinality-limit-for-a-metric).

There is NO ability to revert to old behavior.
([#5909](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5909))

* Exposed a `public` constructor on `Batch<T>` which accepts a single instance
of `T` to be contained in the batch.
Expand Down