Merge branch 'main' into feature/prometheus-scope-info

.github/workflows/codeql-analysis.yml

@@ -36,7 +36,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -47,7 +47,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # Command-line programs to run using the OS shell.
     # https://git.io/JvXDl
@@ -61,4 +61,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3

Directory.Packages.props

@@ -1,7 +1,7 @@
 <Project>
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-    <OTelLatestStableVer>1.6.0</OTelLatestStableVer>
+    <OTelLatestStableVer>1.7.0</OTelLatestStableVer>
   </PropertyGroup>
 
   <!--

OpenTelemetry.sln

@@ -32,7 +32,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E
 		build\docfx.cmd = build\docfx.cmd
 		build\docker-compose.net6.0.yml = build\docker-compose.net6.0.yml
 		build\docker-compose.net7.0.yml = build\docker-compose.net7.0.yml
-		build\docker-compose.net8.0.yml = build\docker-compose.net8.0.yml
 		build\finalize-publicapi.ps1 = build\finalize-publicapi.ps1
 		build\GlobalAttrExclusions.txt = build\GlobalAttrExclusions.txt
 		build\opentelemetry-icon-color.png = build\opentelemetry-icon-color.png
@@ -92,8 +91,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{
 	ProjectSection(SolutionItems) = preProject
 		.github\workflows\ci-aot-md.yml = .github\workflows\ci-aot-md.yml
 		.github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml
-		.github\workflows\ci-concurrency.yml = .github\workflows\ci-concurrency.yml
 		.github\workflows\ci-concurrency-md.yml = .github\workflows\ci-concurrency-md.yml
+		.github\workflows\ci-concurrency.yml = .github\workflows\ci-concurrency.yml
 		.github\workflows\ci-instrumentation-libraries-md.yml = .github\workflows\ci-instrumentation-libraries-md.yml
 		.github\workflows\ci-instrumentation-libraries.yml = .github\workflows\ci-instrumentation-libraries.yml
 		.github\workflows\ci-md.yml = .github\workflows\ci-md.yml
@@ -266,6 +265,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Shared", "Shared", "{A49299
 	ProjectSection(SolutionItems) = preProject
 		src\Shared\ActivityHelperExtensions.cs = src\Shared\ActivityHelperExtensions.cs
 		src\Shared\ActivityInstrumentationHelper.cs = src\Shared\ActivityInstrumentationHelper.cs
+		src\Shared\DiagnosticDefinitions.cs = src\Shared\DiagnosticDefinitions.cs
 		src\Shared\ExceptionExtensions.cs = src\Shared\ExceptionExtensions.cs
 		src\Shared\Guard.cs = src\Shared\Guard.cs
 		src\Shared\HttpSemanticConventionHelper.cs = src\Shared\HttpSemanticConventionHelper.cs
@@ -323,6 +323,19 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "links-creation", "docs\trace\links-creation-with-new-activities\links-creation.csproj", "{B4856711-6D4C-4246-A686-49458D4C1301}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}"
+	ProjectSection(SolutionItems) = preProject
+		docs\diagnostics\README.md = docs\diagnostics\README.md
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "experimental-apis", "experimental-apis", "{17A22B0E-6EC3-4A39-B955-0A486AD06699}"
+	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
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -650,6 +663,8 @@ Global
 		{1C459B5B-C702-46FF-BF1A-EE795E420FFA} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC}
 		{99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705}
 		{B4856711-6D4C-4246-A686-49458D4C1301} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
+		{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40} = {7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}
+		{17A22B0E-6EC3-4A39-B955-0A486AD06699} = {52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}

build/Common.props

@@ -9,6 +9,8 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <!-- Suppress warnings for repo code using experimental features -->
+    <NoWarn>$(NoWarn);OTEL1000;OTEL1001;OTEL1002</NoWarn>
     <!--temporarily disable. See 3958-->
     <!--<AnalysisLevel>latest-All</AnalysisLevel>-->
   </PropertyGroup>

build/RELEASING.md

@@ -84,7 +84,16 @@ Only for Maintainers.
     git push origin 1.0.0-rc9.7
     ```
 
-    If releasing both, push both tags above.
+    If releasing only a particular non-core component which has a dedicated
+    MinverTagPrefix such as AspNetCore instrumentation, only add and push the
+    tag with that particular prefix. For example:
+
+    ```sh
+    git tag -a Instrumentation.AspNetCore-1.6.0 -m "1.6.0 of AspNetCore instrumentation library"
+    git push origin Instrumentation.AspNetCore-1.6.0
+    ```
+
+    If releasing multiple kinds of components, push both tags for each of them.
 
  7. Go to the [list of
     tags](https://github.com/open-telemetry/opentelemetry-dotnet/tags)

docs/diagnostics/README.md

@@ -0,0 +1,23 @@
+# OpenTelemetry Diagnostics
+
+This document describes the diagnostic categories used in OpenTelemetry .NET
+components. Diagnostics are used by the compiler to report information to users
+about experimental and/or obsolete code being invoked or to suggest improvements
+to specific code patterns identified through static analysis.
+
+## Experimental APIs
+
+Range: OTEL1XXX
+
+Experimental APIs exposed in OpenTelemetry .NET pre-relase builds. APIs are
+exposed experimentally when either the OpenTelemetry Specification has
+explicitly marked some feature as
+[experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md)
+or when the SIG members are still working through the design for a feature and
+want to solicit feedback from the community.
+
+> **Note** Experimental APIs are exposed as `public` in pre-release builds and
+> `internal` in stable builds.
+
+For defined diagnostics see: [OpenTelemetry .NET Experimental
+APIs](./experimental-apis/README.md)

docs/diagnostics/experimental-apis/OTEL1000.md

@@ -0,0 +1,42 @@
+# OpenTelemetry .NET Diagnostic: OTEL1000
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `LoggerProviderBuilder`
+* `LoggerProvider`
+* `IDeferredLoggerProviderBuilder`
+
+Experimental APIs may be changed or removed in the future.
+
+## Details
+
+The OpenTelemetry Specification defines a `LoggerProvider` as part of its
+[API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md)
+&
+[SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md)
+components.
+
+The SDK allows calling `Shutdown` and `ForceFlush` on the `LoggerProvider` and
+also allows processors to be added dynamically to a pipeline after its creation.
+
+Today the OpenTelemetry .NET log pipeline is built on top of the
+Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory`
+APIs which do not expose such features.
+
+We also have an issue with the `ILoggingBuilder.AddOpenTelemetry` API in that it
+interacts with the `OpenTelemetryLoggerOptions` class. Options classes are NOT
+available until the `IServiceProvider` is available and services can no longer
+be registered at that point. This prevents the current logging pipeline from
+exposing the same dependency injection surface we have for traces and metrics.
+
+We are exposing these APIs to solve these issues and gather feedback about their
+usefulness.
+
+## Logs Bridge API
+
+The OpenTelemetry Specification defines a Logs Bridge API which is rooted off of
+the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log
+records. See [OTEL1001](./OTEL1001.md) for details about the Logs Bridge API
+implementation status.

docs/diagnostics/experimental-apis/OTEL1001.md

@@ -0,0 +1,35 @@
+# OpenTelemetry .NET Diagnostic: OTEL1001
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `LoggerProvider.GetLogger`
+* `Logger`
+* `LogRecordAttributeList`
+* `LogRecordData`
+* `LogRecordSeverity`
+
+Experimental APIs may be changed or removed in the future.
+
+## Details
+
+The OpenTelemetry Specification defines a [Logs Bridge
+API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md).
+
+The Logs Bridge API is used by library authors to build log appenders which
+route messages from different log frameworks into OpenTelemetry.
+
+Today the OpenTelemetry .NET log pipeline is built on top of the
+Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory`
+APIs.
+
+We are exposing these APIs gather feedback about their usefulness. An
+alternative approach may be taken which would be to append into `ILogger`
+instead of OpenTelemetry directly.
+
+## LoggerProvider API
+
+The OpenTelemetry Specification defines a `LoggerProvider` API. See
+[OTEL1000](./OTEL1000.md) for details about the `LoggerProvider` implementation
+status.

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.

docs/diagnostics/experimental-apis/README.md

@@ -0,0 +1,48 @@
+# OpenTelemetry .NET Experimental APIs
+
+This document describes experimental APIs exposed in OpenTelemetry .NET
+pre-relase builds. APIs are exposed experimentally when either the OpenTelemetry
+Specification has explicitly marked some feature as
+[experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md)
+or when the SIG members are still working through the design for a feature and
+want to solicit feedback from the community.
+
+> **Note**
+> Experimental APIs are exposed as `public` in pre-release builds and `internal`
+> in stable builds.
+
+## Active
+
+Experimental APIs available in the pre-release builds:
+
+### OTEL1000
+
+Description: `LoggerProvider` and `LoggerProviderBuilder`
+
+Details: [OTEL1000](./OTEL1000.md)
+
+### OTEL1001
+
+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:
+
+<!-- When an experimental API is released or removed:
+ 1) Move the section from above down here.
+ 2) Delete the individual file from the repo and switch the link here to a
+    permalink to the last version.
+ 3) Add the version info for when the API was released stable or removed. If
+    removed add details for alternative solution or reasoning.
+-->
+
+None

docs/metrics/exemplars/docker-compose.yaml

@@ -48,4 +48,3 @@ services:
       - GF_FEATURE_TOGGLES_ENABLE=traceqlEditor
     ports:
       - "3000:3000"
-

docs/trace/README.md

@@ -0,0 +1,49 @@
+# OpenTelemetry .NET Traces
+
+## Best Practices
+
+### ActivitySource singleton
+
+`ActivitySource` SHOULD only be created once and reused throughout the
+application lifetime. This
+[example](./getting-started-console/Program.cs) shows how
+`ActivitySource` is created as a `static` field and then used in the
+application. You could also look at this ASP.NET Core
+[example](../../examples/AspNetCore/Program.cs) which shows a more Dependency
+Injection friendly way of doing this by extracting the `ActivitySource` into a
+dedicated class called
+[Instrumentation](../../examples/AspNetCore/Instrumentation.cs) which is then
+added as a `Singleton` service.
+
+### Manually creating Activities
+
+As shown in the [getting started](getting-started-console/README.md) guide, it
+is very easy to manually create `Activity`. Due to this, it can be tempting to
+create too many activities (eg: for each method call). In addition to being
+expensive, excessive activities can also make trace visualization harder.
+Instead of manually creating `Activity`, check if you can leverage
+instrumentation libraries, such as [ASP.NET
+Core](../../src/OpenTelemetry.Instrumentation.AspNetCore/README.md),
+[HttpClient](../../src/OpenTelemetry.Instrumentation.Http/README.md) which will
+not only create and populate `Activity` with tags(attributes), but also take
+care of propagating/restoring the context across process boundaries. If the
+`Activity` produced by the instrumentation library is missing some information
+you need, it is generally recommended to enrich the existing Activity with that
+information, as opposed to creating a new one.
+
+## Common issues that lead to missing traces
+
+- The `ActivitySource` used to create the `Activity` is not added to the
+  `TracerProvider`. Use `AddSource` method to enable the activity from a given
+  `ActivitySource`.
+- `TracerProvider` is disposed too early. You need to ensure that the
+  `TracerProvider` instance is kept active for traces to be collected. In a
+  typical application, a single TracerProvider is built at application startup,
+  and is disposed of at application shutdown. For an ASP.NET Core application,
+  use `AddOpenTelemetry` and `WithTraces` methods from the
+  `OpenTelemetry.Extensions.Hosting` package to correctly setup
+  `TracerProvider`. Here's a [sample ASP.NET Core
+  app](../../examples/AspNetCore/Program.cs) for reference. For simpler
+  applications such as Console apps, refer to this
+  [example](../../docs/trace/getting-started-console/Program.cs).
+- TODO: Sampling

examples/AspNetCore/Controllers/WeatherForecastController.cs

@@ -49,7 +49,7 @@ public IEnumerable<WeatherForecast> Get()
         // that calculating the forecast is an expensive operation and therefore
         // something to be distinguished from the overall request.
         // Note: Tags can be added to the current activity without the need for
-        // a manual activity using Acitivty.Current?.SetTag()
+        // a manual activity using Activity.Current?.SetTag()
         using var activity = this.activitySource.StartActivity("calculate forecast");
 
         var rng = new Random();

src/OpenTelemetry.Api.ProviderBuilderExtensions/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.7.0
+
+Released 2023-Dec-08
+
 ## 1.7.0-rc.1
 
 Released 2023-Nov-29

src/OpenTelemetry.Api.ProviderBuilderExtensions/Logs/OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.cs

@@ -14,6 +14,9 @@ namespace OpenTelemetry.Logs;
 /// Contains extension methods for the <see cref="LoggerProviderBuilder"/> class.
 /// </summary>
 #if EXPOSE_EXPERIMENTAL_FEATURES
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 internal