From 38468744a5fdd9a14c51aa6eb23ebc0b1b51317d Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 11 Dec 2023 12:17:18 -0800 Subject: [PATCH] [sdk-metrics] ExperimentalAttribute decorations for experimental exemplar APIs (#5153) Co-authored-by: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com> --- OpenTelemetry.sln | 1 + build/Common.props | 2 +- .../diagnostics/experimental-apis/OTEL1002.md | 30 +++++++++++++++++++ docs/diagnostics/experimental-apis/README.md | 6 ++++ .../Builder/MeterProviderBuilderExtensions.cs | 5 +++- .../Exemplar/AlwaysOffExemplarFilter.cs | 10 ++++++- .../Exemplar/AlwaysOnExemplarFilter.cs | 8 +++++ .../Metrics/Exemplar/Exemplar.cs | 8 +++++ .../Metrics/Exemplar/ExemplarFilter.cs | 8 +++++ .../Exemplar/TraceBasedExemplarFilter.cs | 8 +++++ src/Shared/DiagnosticDefinitions.cs | 1 + 11 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 docs/diagnostics/experimental-apis/OTEL1002.md diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index f4d72580b..8a158c98c 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -332,6 +332,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "experimental-apis", "experi ProjectSection(SolutionItems) = preProject docs\diagnostics\experimental-apis\OTEL1000.md = docs\diagnostics\experimental-apis\OTEL1000.md docs\diagnostics\experimental-apis\OTEL1001.md = docs\diagnostics\experimental-apis\OTEL1001.md + docs\diagnostics\experimental-apis\OTEL1002.md = docs\diagnostics\experimental-apis\OTEL1002.md docs\diagnostics\experimental-apis\README.md = docs\diagnostics\experimental-apis\README.md EndProjectSection EndProject diff --git a/build/Common.props b/build/Common.props index 758306e55..763c91d05 100644 --- a/build/Common.props +++ b/build/Common.props @@ -10,7 +10,7 @@ enable enable - $(NoWarn);OTEL1000;OTEL1001 + $(NoWarn);OTEL1000;OTEL1001;OTEL1002 diff --git a/docs/diagnostics/experimental-apis/OTEL1002.md b/docs/diagnostics/experimental-apis/OTEL1002.md new file mode 100644 index 000000000..8371f0d3b --- /dev/null +++ b/docs/diagnostics/experimental-apis/OTEL1002.md @@ -0,0 +1,30 @@ +# OpenTelemetry .NET Diagnostic: OTEL1002 + +## Overview + +This is an Experimental API diagnostic covering the following APIs: + +* `AlwaysOnExemplarFilter` +* `AlwaysOffExemplarFilter` +* `Exemplar` +* `ExemplarFilter` +* `MeterProviderBuilder.SetExemplarFilter` extension method +* `TraceBasedExemplarFilter` + +Experimental APIs may be changed or removed in the future. + +## Details + +The OpenTelemetry Specification defines an [Exemplar +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar) +in the Metrics SDK. + +From the specification: + +> Exemplars are example data points for aggregated data. They provide specific +> context to otherwise general aggregations. Exemplars allow correlation between +> aggregated metric data and the original API calls where measurements are +> recorded. + +We are exposing these APIs experimentally until the specification declares them +stable. diff --git a/docs/diagnostics/experimental-apis/README.md b/docs/diagnostics/experimental-apis/README.md index afd255019..71a2d418f 100644 --- a/docs/diagnostics/experimental-apis/README.md +++ b/docs/diagnostics/experimental-apis/README.md @@ -27,6 +27,12 @@ Description: Logs Bridge API Details: [OTEL1001](./OTEL1001.md) +### OTEL1002 + +Description: Metrics Exemplar Support + +Details: [OTEL1002](./OTEL1002.md) + ## Inactive Experimental APIs which have been released stable or removed: diff --git a/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs b/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs index 03c3d48eb..11844d3e7 100644 --- a/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs +++ b/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs @@ -323,6 +323,9 @@ public static class MeterProviderBuilderExtensions /// . /// ExemplarFilter to use. /// The supplied for chaining. +#if NET8_0_OR_GREATER + [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// @@ -334,7 +337,7 @@ public static class MeterProviderBuilderExtensions /// The supplied for chaining. internal #endif - static MeterProviderBuilder SetExemplarFilter(this MeterProviderBuilder meterProviderBuilder, ExemplarFilter exemplarFilter) + static MeterProviderBuilder SetExemplarFilter(this MeterProviderBuilder meterProviderBuilder, ExemplarFilter exemplarFilter) { Guard.ThrowIfNull(exemplarFilter); diff --git a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs index 8ab9f471f..b6c7973b9 100644 --- a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs +++ b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs @@ -1,6 +1,11 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 +#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; +#endif + namespace OpenTelemetry.Metrics; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -9,6 +14,9 @@ namespace OpenTelemetry.Metrics; /// Using this ExemplarFilter is as good as disabling Exemplar feature. /// /// +#if NET8_0_OR_GREATER +[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// @@ -17,7 +25,7 @@ public /// internal #endif - sealed class AlwaysOffExemplarFilter : ExemplarFilter +sealed class AlwaysOffExemplarFilter : ExemplarFilter { /// public override bool ShouldSample(long value, ReadOnlySpan> tags) diff --git a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs index 49f4bfb59..7be5d04db 100644 --- a/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs +++ b/src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs @@ -1,6 +1,11 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 +#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; +#endif + namespace OpenTelemetry.Metrics; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -8,6 +13,9 @@ namespace OpenTelemetry.Metrics; /// An ExemplarFilter which makes all measurements eligible for being an Exemplar. /// /// +#if NET8_0_OR_GREATER +[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// diff --git a/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs b/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs index 5efd77a59..d635a1a4a 100644 --- a/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs +++ b/src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs @@ -1,6 +1,11 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 +#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; +#endif + using System.Diagnostics; namespace OpenTelemetry.Metrics; @@ -10,6 +15,9 @@ namespace OpenTelemetry.Metrics; /// Represents an Exemplar data. /// /// WARNING: This is an experimental API which might change or be removed in the future. Use at your own risk. +#if NET8_0_OR_GREATER +[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// diff --git a/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs index ca2617d22..3af62b66c 100644 --- a/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs +++ b/src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs @@ -1,6 +1,11 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 +#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; +#endif + namespace OpenTelemetry.Metrics; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -8,6 +13,9 @@ namespace OpenTelemetry.Metrics; /// The base class for defining Exemplar Filter. /// /// +#if NET8_0_OR_GREATER +[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// diff --git a/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs b/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs index 8fcf364f4..6d176f8a1 100644 --- a/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs +++ b/src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs @@ -1,6 +1,11 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 +#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; +#endif + using System.Diagnostics; namespace OpenTelemetry.Metrics; @@ -11,6 +16,9 @@ namespace OpenTelemetry.Metrics; /// which are recorded in the context of a sampled parent activity (span). /// /// +#if NET8_0_OR_GREATER +[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif public #else /// diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index cc34e86c8..8d2bf4972 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -11,4 +11,5 @@ internal static class DiagnosticDefinitions public const string LoggerProviderExperimentalApi = "OTEL1000"; public const string LogsBridgeExperimentalApi = "OTEL1001"; + public const string ExemplarExperimentalApi = "OTEL1002"; }