Merge branch 'main' of https://github.com/RichardChukwu/opentelemetry-dotnet

Author: RichardChukwu

CONTRIBUTING.md

@@ -203,13 +203,19 @@ Open a pull request against the main `opentelemetry-dotnet` repo.
 * If the PR is not ready for review, please mark it as
   [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
 * Make sure CLA is signed and all required CI checks are clear.
-* Submit small, focused PRs addressing a single
-  concern/issue.
+* Submit small, focused PRs addressing a single concern/issue.
 * Make sure the PR title reflects the contribution.
 * Write a summary that helps understand the change.
 * Include usage examples in the summary, where applicable.
 * Include benchmarks (before/after) in the summary, for contributions that are
   performance enhancements.
+* We are open to bot generated PRs or AI/LLM assisted PRs. Actually, we are
+  using
+  [dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates)
+  to automate the security updates. However, if you use bots to generate spam
+  PRs (e.g. incorrect, noisy, non-improvements, unintelligible, trying to sell
+  your product, etc.), we might close the PR right away with a warning, and if
+  you keep doing so, we might block your user account.
 
 ### How to get pull requests merged
 
@@ -302,23 +308,6 @@ analysis](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/overview
 [Common.props](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/build/Common.props)
 new projects must NOT manually override these settings.
 
-## New code
-
-New code files MUST enable [nullable reference
-types](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/nullable-reference-types)
-manually in projects where it is not automatically enabled project-wide. This is
-done by specifying `#nullable enable` towards the top of the file (usually after
-the copyright header). We are currently working towards enabling nullable
-context in every project by updating code as it is worked on, this requirement
-is to make sure the surface area of code needing updates is shrinking and not
-expanding.
-
-> [!NOTE]
-> The first time a project is updated to use nullable context in public APIs
-some housekeeping needs to be done in public API definitions (`.publicApi`
-folder). This can be done automatically via a code fix offered by the public API
-analyzer.
-
 ## License requirements
 
 OpenTelemetry .NET is licensed under the [Apache License, Version

Directory.Packages.props

@@ -4,6 +4,13 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
     <OTelLatestStableVer>1.9.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>
+
     <!-- Mitigate https://msrc.microsoft.com/update-guide/vulnerability/CVE-2024-43485. -->
     <SystemTextEncodingsWebOutOfBandMinimumCoreAppVer>8.0.0</SystemTextEncodingsWebOutOfBandMinimumCoreAppVer>
     <SystemTextJsonOutOfBandMinimumCoreAppVer>8.0.5</SystemTextJsonOutOfBandMinimumCoreAppVer>
@@ -15,12 +22,6 @@
       vulnerability in the NuGet packages that are published from this repository.
   -->
   <ItemGroup>
-    <PackageVersion Include="Google.Protobuf" Version="[3.22.5,4.0)" />
-    <PackageVersion Include="Grpc" Version="[2.44.0,3.0)" />
-    <PackageVersion Include="Grpc.Net.Client" Version="[2.52.0,3.0)" />
-    <PackageVersion Include="Microsoft.AspNetCore.Http.Abstractions" Version="[2.1.1,6.0)" />
-    <PackageVersion Include="Microsoft.AspNetCore.Http.Features" Version="[2.1.1,6.0)" />
-
     <!--
         Typically, for the Microsoft.Extensions.* packages relating to DI Abstractions, Hosting Abstractions, and Logging,
         the latest stable version should be used because:
@@ -30,16 +31,18 @@
         3) Since version 3.1.0, the .NET runtime team is holding a high bar for backward compatibility on
           these packages even during major version bumps, so compatibility is not a concern here.
     -->
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Diagnostics.Abstractions" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Configuration" Version="$(LatestRuntimeOutOfBandVer)" />
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="$(LatestRuntimeOutOfBandVer)" />
 
-    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Diagnostics.Abstractions" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Configuration" Version="9.0.0-rc.1.24431.7" />
-    <PackageVersion Include="Microsoft.Extensions.Options" Version="9.0.0-rc.1.24431.7" />
-
+    <!--
+        OTel packages always point to latest stable release.
+    -->
     <PackageVersion Include="OpenTelemetry" Version="[$(OTelLatestStableVer),2.0)" />
     <PackageVersion Include="OpenTelemetry.Api" Version="[$(OTelLatestStableVer),2.0)" />
     <PackageVersion Include="OpenTelemetry.Api.ProviderBuilderExtensions" Version="[$(OTelLatestStableVer),2.0)" />
@@ -50,14 +53,22 @@
 
     <!--
         Typically, the latest stable version of System.Diagnostics.DiagnosticSource should be used here because:
-        1) Each major version bump will have some new OpenTelemetry API capabilities (e.g. .NET 6 introduced Meter
-          API, .NET 7 added UpDownCounter, .NET 8 is adding Meter/Instrument level attributes support, .NET 9 might
-          add Advice/Hint API) that the OpenTelemetry components rely on.
+        1) Each major version bump will likely have some new OpenTelemetry capabilities (e.g. .NET 6 introduced Meter
+          API, .NET 7 added UpDownCounter, .NET 8 added Meter/Instrument level attributes support, .NET 9 added
+          Advice/Hint API, etc.).
         2) Each minor version bump is normally security hotfixes or critical bug fixes.
         3) The .NET runtime team provides extra backward compatibility guarantee to System.Diagnostics.DiagnosticSource
           even during major version bumps, so compatibility is not a concern here.
     -->
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="9.0.0-rc.1.24431.7" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="$(LatestRuntimeOutOfBandVer)" />
+
+    <!--
+        We use conservative versions of these packages where an upgrade might
+        introduce breaking changes.
+    -->
+    <PackageVersion Include="Google.Protobuf" Version="[3.22.5,4.0)" />
+    <PackageVersion Include="Grpc" Version="[2.44.0,3.0)" />
+    <PackageVersion Include="Grpc.Net.Client" Version="[2.52.0,3.0)" />
   </ItemGroup>
 
   <ItemGroup>
@@ -92,10 +103,10 @@
     <PackageVersion Include="Microsoft.CSharp" Version="[4.7.0]" />
     <PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="[3.11.0-beta1.23525.2]" />
     <PackageVersion Include="Microsoft.Coyote" Version="1.7.11" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="[9.0.0-rc.1.24431.7,)" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="[9.0.0-rc.1.24431.7,)" />
-    <PackageVersion Include="Microsoft.Extensions.Http" Version="[9.0.0-rc.1.24431.7,)" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="[9.0.0-rc.1.24431.7,)" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="$(LatestRuntimeOutOfBandVer)" />
+    <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.NETFramework.ReferenceAssemblies" Version="[1.0.3,2.0)" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="[17.11.0,18.0.0)" />

docs/logs/redaction/MyRedactionProcessor.cs

@@ -15,33 +15,33 @@ public override void OnEnd(LogRecord logRecord)
         }
     }
 
-    internal sealed class MyClassWithRedactionEnumerator : IReadOnlyList<KeyValuePair<string, object>>
+    internal sealed class MyClassWithRedactionEnumerator : IReadOnlyList<KeyValuePair<string, object?>>
     {
-        private readonly IReadOnlyList<KeyValuePair<string, object>> state;
+        private readonly IReadOnlyList<KeyValuePair<string, object?>> state;
 
-        public MyClassWithRedactionEnumerator(IReadOnlyList<KeyValuePair<string, object>> state)
+        public MyClassWithRedactionEnumerator(IReadOnlyList<KeyValuePair<string, object?>> state)
         {
             this.state = state;
         }
 
         public int Count => this.state.Count;
 
-        public KeyValuePair<string, object> this[int index]
+        public KeyValuePair<string, object?> this[int index]
         {
             get
             {
                 var item = this.state[index];
                 var entryVal = item.Value?.ToString();
                 if (entryVal != null && entryVal.Contains("<secret>"))
                 {
-                    return new KeyValuePair<string, object>(item.Key, "newRedactedValueHere");
+                    return new KeyValuePair<string, object?>(item.Key, "newRedactedValueHere");
                 }
 
                 return item;
             }
         }
 
-        public IEnumerator<KeyValuePair<string, object>> GetEnumerator()
+        public IEnumerator<KeyValuePair<string, object?>> GetEnumerator()
         {
             for (var i = 0; i < this.Count; i++)
             {

docs/logs/redaction/redaction.csproj

@@ -1,8 +1,4 @@
 <Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <!-- this is temporary. will remove in future PR. -->
-    <Nullable>disable</Nullable>
-  </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
   </ItemGroup>

docs/metrics/customizing-the-sdk/Program.cs

@@ -40,6 +40,12 @@ public static void Main()
             // Drop the instrument "MyCounterDrop".
             .AddView(instrumentName: "MyCounterDrop", MetricStreamConfiguration.Drop)
 
+            // Configure the Explicit Bucket Histogram aggregation with custom boundaries and new name.
+            .AddView(instrumentName: "histogramWithMultipleAggregations", new ExplicitBucketHistogramConfiguration() { Boundaries = new double[] { 10, 20 }, Name = "MyHistogramWithExplicitHistogram" })
+
+            // Use Base2 Exponential Bucket Histogram aggregation and new name.
+            .AddView(instrumentName: "histogramWithMultipleAggregations", new Base2ExponentialBucketHistogramConfiguration() { Name = "MyHistogramWithBase2ExponentialBucketHistogram" })
+
             // An instrument which does not match any views
             // gets processed with default behavior. (SDK default)
             // Uncommenting the following line will
@@ -70,6 +76,12 @@ public static void Main()
             exponentialBucketHistogram.Record(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2"));
         }
 
+        var histogramWithMultipleAggregations = Meter1.CreateHistogram<long>("histogramWithMultipleAggregations");
+        for (int i = 0; i < 20000; i++)
+        {
+            histogramWithMultipleAggregations.Record(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2"));
+        }
+
         var counterCustomTags = Meter1.CreateCounter<long>("MyCounterCustomTags");
         for (int i = 0; i < 20000; i++)
         {

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

@@ -245,6 +245,90 @@ within the maximum number of buckets defined by `MaxSize`. The default
         new Base2ExponentialBucketHistogramConfiguration { MaxSize = 40 })
 ```
 
+#### Produce multiple metrics from single instrument
+
+When an instrument matches multiple views, it can generate multiple metrics. For
+instance, if an instrument is matched by two different view configurations, it
+will result in two separate metrics being produced from that single instrument.
+Below is an example demonstrating how to leverage this capability to create two
+independent metrics from a single instrument. In this example, a histogram
+instrument is used to report measurements, and views are configured to produce
+two metrics : one aggregated using `ExplicitBucketHistogramConfiguration` and the
+other using `Base2ExponentialBucketHistogramConfiguration`.
+
+```csharp
+    var histogramWithMultipleAggregations = meter.CreateHistogram<long>("HistogramWithMultipleAggregations");
+
+    // Configure the Explicit Bucket Histogram aggregation with custom boundaries and new name.
+    .AddView(instrumentName: "HistogramWithMultipleAggregations", new ExplicitBucketHistogramConfiguration() { Boundaries = new double[] { 10, 20 }, Name = "MyHistogramWithExplicitHistogram" })
+
+    // Use Base2 Exponential Bucket Histogram aggregation and new name.
+    .AddView(instrumentName: "HistogramWithMultipleAggregations", new Base2ExponentialBucketHistogramConfiguration() { Name = "MyHistogramWithBase2ExponentialBucketHistogram" })
+
+    // Both views rename the metric to avoid name conflicts. However, in this case,
+    // renaming one would be sufficient.
+
+    // This measurement will be aggregated into two separate metrics.
+    histogramWithMultipleAggregations.Record(10, new("tag1", "value1"), new("tag2", "value2"));
+```
+
+When using views that produce multiple metrics from single instrument, it's
+crucial to rename the metric to prevent conflicts. In the event of conflict,
+OpenTelemetry will emit an internal warning but will still export both metrics.
+The impact of this behavior depends on the backend or receiver being used. You
+can refer to [OpenTelemetry's
+specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#opentelemetry-protocol-data-model-consumer-recommendations)
+for more details.
+
+Below example is showing the *BAD* practice. DO NOT FOLLOW it.
+
+```csharp
+    var histogram = meter.CreateHistogram<long>("MyHistogram");
+
+    // Configure a view to aggregate based only on the "location" tag.
+    .AddView(instrumentName: "MyHistogram", metricStreamConfiguration: new MetricStreamConfiguration
+        {
+            TagKeys = new string[] { "location" },
+        })
+
+    // Configure another view to aggregate based only on the "status" tag.
+    .AddView(instrumentName: "MyHistogram", metricStreamConfiguration: new MetricStreamConfiguration
+        {
+            TagKeys = new string[] { "status" },
+        })
+
+    // The measurement below will be aggregated into two metric streams, but both will have the same name.
+    // OpenTelemetry will issue a warning about this conflict and pass both streams to the exporter.
+    // However, this may cause issues depending on the backend.
+    histogram.Record(10, new("location", "seattle"), new("status", "OK"));
+```
+
+The modified version, avoiding name conflict is shown below:
+
+```csharp
+    var histogram = meter.CreateHistogram<long>("MyHistogram");
+
+    // Configure a view to aggregate based only on the "location" tag,
+    // and rename the metric.
+    .AddView(instrumentName: "MyHistogram", metricStreamConfiguration: new MetricStreamConfiguration
+        {
+            Name = "MyHistogramWithLocation",
+            TagKeys = new string[] { "location" },
+        })
+
+    // Configure a view to aggregate based only on the "status" tag,
+    // and rename the metric.
+    .AddView(instrumentName: "MyHistogram", metricStreamConfiguration: new MetricStreamConfiguration
+        {
+            Name = "MyHistogramWithStatus",
+            TagKeys = new string[] { "status" },
+        })
+
+    // The measurement below will be aggregated into two separate metrics, "MyHistogramWithLocation"
+    // and "MyHistogramWithStatus".
+    histogram.Record(10, new("location", "seattle"), new("status", "OK"));
+```
+
 > [!NOTE]
 > The SDK currently does not support any changes to `Aggregation` type
 by using Views.

docs/trace/customizing-the-sdk/customizing-the-sdk.csproj

@@ -1,8 +1,4 @@
 <Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <!-- this is temporary. will remove in future PR. -->
-    <Nullable>disable</Nullable>
-  </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
   </ItemGroup>

examples/Console/Examples.Console.csproj

@@ -4,9 +4,6 @@
     <OutputType>Exe</OutputType>
     <TargetFramework>$(DefaultTargetFrameworkForExampleApps)</TargetFramework>
     <NoWarn>$(NoWarn),CS0618</NoWarn>
-
-    <!-- this is temporary. will remove in future PR. -->
-    <Nullable>disable</Nullable>
   </PropertyGroup>
 
   <ItemGroup>

examples/Console/InstrumentationWithActivitySource.cs

@@ -47,13 +47,13 @@ public void Start(string url)
                         var context = this.listener.GetContext();
 
                         using var activity = source.StartActivity(
-                            $"{context.Request.HttpMethod}:{context.Request.Url.AbsolutePath}",
+                            $"{context.Request.HttpMethod}:{context.Request.Url!.AbsolutePath}",
                             ActivityKind.Server);
 
                         var headerKeys = context.Request.Headers.AllKeys;
                         foreach (var headerKey in headerKeys)
                         {
-                            string headerValue = context.Request.Headers[headerKey];
+                            string? headerValue = context.Request.Headers[headerKey];
                             activity?.SetTag($"http.header.{headerKey}", headerValue);
                         }
 
@@ -62,7 +62,7 @@ public void Start(string url)
                         using (var reader = new StreamReader(context.Request.InputStream, context.Request.ContentEncoding))
                         {
                             requestContent = reader.ReadToEnd();
-                            childSpan.AddEvent(new ActivityEvent("StreamReader.ReadToEnd"));
+                            childSpan?.AddEvent(new ActivityEvent("StreamReader.ReadToEnd"));
                         }
 
                         activity?.SetTag("request.content", requestContent);
@@ -90,8 +90,8 @@ public void Dispose()
 
     private class SampleClient : IDisposable
     {
-        private CancellationTokenSource cts;
-        private Task requestTask;
+        private CancellationTokenSource? cts;
+        private Task? requestTask;
 
         public void Start(string url)
         {
@@ -154,7 +154,7 @@ public void Dispose()
             if (this.cts != null)
             {
                 this.cts.Cancel();
-                this.requestTask.Wait();
+                this.requestTask!.Wait();
                 this.requestTask.Dispose();
                 this.cts.Dispose();
             }