Merge branch 'main' into main

Directory.Packages.props

@@ -2,14 +2,14 @@
 
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-    <OTelLatestStableVer>1.9.0</OTelLatestStableVer>
+    <OTelLatestStableVer>1.10.0</OTelLatestStableVer>
 
     <!--
         This is typically the latest annual release of .NET. Use this wherever
         possible and only deviate (use a specific version) when a package has a
         more specific patch which must be reference directly.
     -->
-    <LatestRuntimeOutOfBandVer>9.0.0-rc.1.24431.7</LatestRuntimeOutOfBandVer>
+    <LatestRuntimeOutOfBandVer>9.0.0</LatestRuntimeOutOfBandVer>
 
     <!-- Mitigate https://msrc.microsoft.com/update-guide/vulnerability/CVE-2024-43485. -->
     <SystemTextEncodingsWebOutOfBandMinimumCoreAppVer>8.0.0</SystemTextEncodingsWebOutOfBandMinimumCoreAppVer>
@@ -106,7 +106,7 @@
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="$(LatestRuntimeOutOfBandVer)" />
     <PackageVersion Include="Microsoft.Extensions.Http" Version="$(LatestRuntimeOutOfBandVer)" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="$(LatestRuntimeOutOfBandVer)" />
-    <PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="[9.0.0-preview.8.24460.1,)" />
+    <PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="[9.0.0,)" />
     <PackageVersion Include="Microsoft.NETFramework.ReferenceAssemblies" Version="[1.0.3,2.0)" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="[17.11.0,18.0.0)" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="[8.0.0,9.0)" />
@@ -129,7 +129,7 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
-    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.0-rc.1.24452.1" />
+    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.0" />
   </ItemGroup>
 
 </Project>

README.md

@@ -179,6 +179,37 @@ Nightly builds from this repo are published to [MyGet](https://www.myget.org),
 and can be installed using the
 `https://www.myget.org/F/opentelemetry/api/v3/index.json` source.
 
+### Digital signing
+
+Starting with the `1.10.0` release the DLLs included in the packages pushed to
+NuGet are digitally signed using [Sigstore](https://www.sigstore.dev/). Within
+each NuGet package the digital signature and its corresponding certificate file
+are placed alongside the shipped DLL(s) in the `/lib` folder. When a project
+targets multiple frameworks each target outputs a dedicated DLL and signing
+artifacts into a sub folder based on the
+[TFM](https://learn.microsoft.com/dotnet/standard/frameworks).
+
+The digitial signature and certificate files share the same name prefix as the
+DLL to ensure easy identification and association.
+
+To verify the integrity of a DLL inside a NuGet package use the
+[cosign](https://github.com/sigstore/cosign) tool from Sigstore:
+
+```bash
+cosign verify-blob \
+    --signature OpenTelemetry.dll-keyless.sig \
+    --certificate OpenTelemetry.dll-keyless.pem.cer \
+    --certificate-identity "https://github.com/open-telemetry/opentelemetry-dotnet/.github/workflows/publish-packages-1.0.yml@refs/tags/core-1.10.0-rc.1" \
+    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+    OpenTelemetry.dll
+```
+
+> [!NOTE]
+> A successful verification outputs `Verify OK`.
+
+For more verification options please refer to the [cosign
+documentation](https://github.com/sigstore/cosign/blob/main/doc/cosign_verify-blob.md).
+
 ## Contributing
 
 For information about contributing to the project see:

RELEASENOTES.md

@@ -14,6 +14,9 @@ directory of each individual package.
 
   * [InstrumentAdvice<T>](https://learn.microsoft.com/dotnet/api/system.diagnostics.metrics.instrumentadvice-1)
 
+    For details see: [Explicit bucket histogram
+    aggregation](./docs/metrics/customizing-the-sdk/README.md#explicit-bucket-histogram-aggregation).
+
   * [Gauge<T>](https://learn.microsoft.com/dotnet/api/system.diagnostics.metrics.gauge-1)
 
   * [ActivitySource.Tags](https://learn.microsoft.com/dotnet/api/system.diagnostics.activitysource.tags)

docs/metrics/customizing-the-sdk/README.md

@@ -200,29 +200,56 @@ used.
 
 ##### Explicit bucket histogram aggregation
 
-By default, the boundaries used for a Histogram are [`{ 0, 5, 10, 25, 50, 75,
-100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000}`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation).
-Views can be used to provide custom boundaries for a Histogram. The measurements
-are then aggregated using the custom boundaries provided instead of the
-default boundaries. This requires the use of
-`ExplicitBucketHistogramConfiguration`.
+By default, the [OpenTelemetry
+Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation)
+defines explicit buckets (aka boundaries) for Histograms as: `[ 0, 5, 10, 25,
+50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 ]`.
 
-```csharp
-    // Change Histogram boundaries to count measurements under the following buckets:
-    // (-inf, 10]
-    // (10, 20]
-    // (20, +inf)
-    .AddView(
-        instrumentName: "MyHistogram",
-        new ExplicitBucketHistogramConfiguration { Boundaries = new double[] { 10, 20 } })
+###### Customizing explicit buckets when using histogram aggregation
 
-    // If you provide an empty `double` array as `Boundaries` to the `ExplicitBucketHistogramConfiguration`,
-    // the SDK will only export the sum, count, min and max for the measurements.
-    // There are no buckets exported in this case.
-    .AddView(
-        instrumentName: "MyHistogram",
-        new ExplicitBucketHistogramConfiguration { Boundaries = Array.Empty<double>() })
-```
+There are two mechanisms available to configure explicit buckets when using
+histogram aggregation:
+
+* View API - Part of the OpenTelemetry .NET SDK.
+* Advice API - Part of the `System.Diagnostics.DiagnosticSource` package
+  starting with version `9.0.0`.
+
+> [!IMPORTANT]
+> When both the View API and Advice API are used, the View API takes precedence.
+  If explicit buckets are not provided by either the View API or the Advice API
+  then the SDK defaults apply.
+
+* View API
+
+  Views can be used to provide custom explicit buckets for a Histogram. This
+  requires the use of `ExplicitBucketHistogramConfiguration`.
+
+  ```csharp
+   // Change Histogram boundaries to count measurements under the following buckets:
+   // (-inf, 10]
+   // (10, 20]
+   // (20, +inf)
+   .AddView(
+       instrumentName: "MyHistogram",
+       new ExplicitBucketHistogramConfiguration { Boundaries = new double[] { 10, 20 } })
+
+   // If you provide an empty `double` array as `Boundaries` to the `ExplicitBucketHistogramConfiguration`,
+   // the SDK will only export the sum, count, min and max for the measurements.
+   // There are no buckets exported in this case.
+   .AddView(
+       instrumentName: "MyHistogram",
+       new ExplicitBucketHistogramConfiguration { Boundaries = Array.Empty<double>() })
+  ```
+
+* Advice API
+
+  Starting with the `1.10.0` SDK, explicit buckets for a Histogram may be provided
+  by instrumentation authors when the instrument is created. This is generally
+  recommended to be used by library authors when the SDK defaults don't match the
+  required granularity for the histogram being emitted.
+
+  See:
+  [InstrumentAdvice&lt;T&gt;](https://learn.microsoft.com/dotnet/api/system.diagnostics.metrics.instrumentadvice-1).
 
 ##### Base2 exponential bucket histogram aggregation
 

global.json

@@ -1,6 +1,6 @@
 {
   "sdk": {
     "rollForward": "latestFeature",
-    "version": "9.0.100-rc.1.24452.12"
+    "version": "9.0.100"
   }
 }

src/OpenTelemetry.Api.ProviderBuilderExtensions/CHANGELOG.md

@@ -7,6 +7,14 @@ Notes](../../RELEASENOTES.md).
 
 ## Unreleased
 
+## 1.10.0
+
+Released 2024-Nov-12
+
+* Updated `Microsoft.Extensions.DependencyInjection.Abstractions` package
+  version to `9.0.0`.
+  ([#5967](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5967))
+
 ## 1.10.0-rc.1
 
 Released 2024-Nov-01

src/OpenTelemetry.Api/.publicApi/Stable/PublicAPI.Shipped.txt

@@ -1,12 +1,4 @@
 #nullable enable
-static OpenTelemetry.Context.RuntimeContext.ContextSlotType.get -> System.Type!
-static OpenTelemetry.Context.RuntimeContext.ContextSlotType.set -> void
-static OpenTelemetry.Context.RuntimeContext.GetSlot<T>(string! slotName) -> OpenTelemetry.Context.RuntimeContextSlot<T>!
-static OpenTelemetry.Context.RuntimeContext.GetValue(string! slotName) -> object?
-static OpenTelemetry.Context.RuntimeContext.GetValue<T>(string! slotName) -> T?
-static OpenTelemetry.Context.RuntimeContext.RegisterSlot<T>(string! slotName) -> OpenTelemetry.Context.RuntimeContextSlot<T>!
-static OpenTelemetry.Context.RuntimeContext.SetValue(string! slotName, object? value) -> void
-static OpenTelemetry.Context.RuntimeContext.SetValue<T>(string! slotName, T value) -> void
 abstract OpenTelemetry.Context.Propagation.TextMapPropagator.Extract<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Func<T, string!, System.Collections.Generic.IEnumerable<string!>?>! getter) -> OpenTelemetry.Context.Propagation.PropagationContext
 abstract OpenTelemetry.Context.Propagation.TextMapPropagator.Fields.get -> System.Collections.Generic.ISet<string!>?
 abstract OpenTelemetry.Context.Propagation.TextMapPropagator.Inject<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Action<T, string!, string!>! setter) -> void
@@ -45,10 +37,10 @@ OpenTelemetry.Context.IRuntimeContextSlotValueAccessor.Value.set -> void
 OpenTelemetry.Context.Propagation.B3Propagator
 OpenTelemetry.Context.Propagation.B3Propagator.B3Propagator() -> void
 OpenTelemetry.Context.Propagation.B3Propagator.B3Propagator(bool singleHeader) -> void
-OpenTelemetry.Context.Propagation.CompositeTextMapPropagator.CompositeTextMapPropagator(System.Collections.Generic.IEnumerable<OpenTelemetry.Context.Propagation.TextMapPropagator!>! propagators) -> void
 OpenTelemetry.Context.Propagation.BaggagePropagator
 OpenTelemetry.Context.Propagation.BaggagePropagator.BaggagePropagator() -> void
 OpenTelemetry.Context.Propagation.CompositeTextMapPropagator
+OpenTelemetry.Context.Propagation.CompositeTextMapPropagator.CompositeTextMapPropagator(System.Collections.Generic.IEnumerable<OpenTelemetry.Context.Propagation.TextMapPropagator!>! propagators) -> void
 OpenTelemetry.Context.Propagation.PropagationContext
 OpenTelemetry.Context.Propagation.PropagationContext.ActivityContext.get -> System.Diagnostics.ActivityContext
 OpenTelemetry.Context.Propagation.PropagationContext.Baggage.get -> OpenTelemetry.Baggage
@@ -176,8 +168,8 @@ override OpenTelemetry.Context.Propagation.BaggagePropagator.Inject<T>(OpenTelem
 override OpenTelemetry.Context.Propagation.CompositeTextMapPropagator.Extract<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Func<T, string!, System.Collections.Generic.IEnumerable<string!>?>! getter) -> OpenTelemetry.Context.Propagation.PropagationContext
 override OpenTelemetry.Context.Propagation.CompositeTextMapPropagator.Fields.get -> System.Collections.Generic.ISet<string!>!
 override OpenTelemetry.Context.Propagation.CompositeTextMapPropagator.Inject<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Action<T, string!, string!>! setter) -> void
-override OpenTelemetry.Context.Propagation.PropagationContext.GetHashCode() -> int
 override OpenTelemetry.Context.Propagation.PropagationContext.Equals(object? obj) -> bool
+override OpenTelemetry.Context.Propagation.PropagationContext.GetHashCode() -> int
 override OpenTelemetry.Context.Propagation.TraceContextPropagator.Extract<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Func<T, string!, System.Collections.Generic.IEnumerable<string!>?>! getter) -> OpenTelemetry.Context.Propagation.PropagationContext
 override OpenTelemetry.Context.Propagation.TraceContextPropagator.Fields.get -> System.Collections.Generic.ISet<string!>!
 override OpenTelemetry.Context.Propagation.TraceContextPropagator.Inject<T>(OpenTelemetry.Context.Propagation.PropagationContext context, T carrier, System.Action<T, string!, string!>! setter) -> void
@@ -208,6 +200,14 @@ static OpenTelemetry.Baggage.SetBaggage(System.Collections.Generic.IEnumerable<S
 static OpenTelemetry.Context.Propagation.PropagationContext.operator !=(OpenTelemetry.Context.Propagation.PropagationContext left, OpenTelemetry.Context.Propagation.PropagationContext right) -> bool
 static OpenTelemetry.Context.Propagation.PropagationContext.operator ==(OpenTelemetry.Context.Propagation.PropagationContext left, OpenTelemetry.Context.Propagation.PropagationContext right) -> bool
 static OpenTelemetry.Context.Propagation.Propagators.DefaultTextMapPropagator.get -> OpenTelemetry.Context.Propagation.TextMapPropagator!
+static OpenTelemetry.Context.RuntimeContext.ContextSlotType.get -> System.Type!
+static OpenTelemetry.Context.RuntimeContext.ContextSlotType.set -> void
+static OpenTelemetry.Context.RuntimeContext.GetSlot<T>(string! slotName) -> OpenTelemetry.Context.RuntimeContextSlot<T>!
+static OpenTelemetry.Context.RuntimeContext.GetValue(string! slotName) -> object?
+static OpenTelemetry.Context.RuntimeContext.GetValue<T>(string! slotName) -> T?
+static OpenTelemetry.Context.RuntimeContext.RegisterSlot<T>(string! slotName) -> OpenTelemetry.Context.RuntimeContextSlot<T>!
+static OpenTelemetry.Context.RuntimeContext.SetValue(string! slotName, object? value) -> void
+static OpenTelemetry.Context.RuntimeContext.SetValue<T>(string! slotName, T value) -> void
 static OpenTelemetry.Trace.ActivityExtensions.GetStatus(this System.Diagnostics.Activity? activity) -> OpenTelemetry.Trace.Status
 static OpenTelemetry.Trace.ActivityExtensions.RecordException(this System.Diagnostics.Activity? activity, System.Exception? ex, in System.Diagnostics.TagList tags) -> void
 static OpenTelemetry.Trace.ActivityExtensions.RecordException(this System.Diagnostics.Activity? activity, System.Exception? ex) -> void

src/OpenTelemetry.Api/CHANGELOG.md

@@ -6,6 +6,14 @@ Notes](../../RELEASENOTES.md).
 
 ## Unreleased
 
+## 1.10.0
+
+Released 2024-Nov-12
+
+* Updated `System.Diagnostics.DiagnosticSource` package version to
+  `9.0.0`.
+  ([#5967](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5967))
+
 ## 1.10.0-rc.1
 
 Released 2024-Nov-01

src/OpenTelemetry.Api/README.md

@@ -332,11 +332,13 @@ chose not to sample this activity.
 
 4. Activity Links
 
-   Apart from the parent-child relation, activities can be linked using
-   `ActivityLinks` which represent the OpenTelemetry
-   [Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#links-between-spans).
-   The linked activities must be provided during the creation time, as shown
-   below.
+   In addition to parent-child relationships, activities can also be linked
+   using `ActivityLinks`, which represent
+   [Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#links-between-spans)
+   in OpenTelemetry. Providing activity links during creation is recommended, as
+   this allows samplers to consider them when deciding whether to sample an
+   activity. However, starting with `System.Diagnostics.DiagnosticSource` 9.0.0,
+   links can also be added after an activity is created.
 
     ```csharp
     var activityLinks = new List<ActivityLink>();
@@ -359,12 +361,19 @@ chose not to sample this activity.
         ActivityKind.Server,
         default(ActivityContext),
         initialTags,
-        activityLinks);
+        activityLinks); // links provided at creation time.
+
+    // One may add links after activity is created too.
+    var linkedContext3 = new ActivityContext(
+        ActivityTraceId.CreateFromString("01260a70a81e1fa3ad5a8acfeaa0f711"),
+        ActivitySpanId.CreateFromString("34739aa9e2239da1"),
+        ActivityTraceFlags.None);
+    activity?.AddLink(linkedContext3);
     ```
 
-    Note that `Activity` above is created with `default(ActivityContext)`
-    parent, which makes it child of implicit `Activity.Current` or orphan if
-    there is no `Current`.
+   Note that `Activity` above is created with `default(ActivityContext)`
+   parent, which makes it child of implicit `Activity.Current` or orphan if
+   there is no `Current`.
 
 ### Adding Events