Merge branch 'main' into net462httpclientmetricsv3

.github/workflows/ci-instrumentation-libraries-md.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462

.github/workflows/ci-instrumentation-libraries.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false  # ensures the entire test matrix is run, even if one permutation fails
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462

.github/workflows/ci-md.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462
@@ -31,7 +31,7 @@ jobs:
     strategy:
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false  # ensures the entire test matrix is run, even if one permutation fails
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462
@@ -44,7 +44,7 @@ jobs:
       fail-fast: false  # ensures the entire test matrix is run, even if one permutation fails
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        version: [ net462, net6.0, net7.0 ]
+        version: [ net462, net6.0, net7.0, net8.0 ]
         exclude:
         - os: ubuntu-latest
           version: net462

.github/workflows/integration-md.yml

@@ -18,22 +18,22 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [net6.0,net7.0]
+        version: [ net6.0, net7.0, net8.0 ]
     steps:
       - run: 'echo "No build required"'
 
   w3c-trace-context-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [net6.0,net7.0]
+        version: [ net6.0, net7.0, net8.0 ]
     steps:
       - run: 'echo "No build required"'
 
   otlp-exporter-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [net6.0,net7.0]
+        version: [ net6.0, net7.0 , net8.0 ]
     steps:
       - run: 'echo "No build required"'

.github/workflows/integration.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        version: [net6.0,net7.0]
+        version: [ net6.0, net7.0 ]
     steps:
       - uses: actions/checkout@v4
 
@@ -28,7 +28,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        version: [net6.0,net7.0]
+        version: [ net6.0, net7.0, net8.0 ]
     steps:
       - uses: actions/checkout@v4
 

build/Common.prod.props

@@ -2,8 +2,6 @@
   <Import Project=".\Common.props" />
 
   <PropertyGroup>
-    <!-- OmniSharp/VS Code requires TargetFrameworks to be in descending order for IntelliSense and analysis. -->
-    <DefaultTargetFrameworks>net6.0;netstandard2.0;net462</DefaultTargetFrameworks>
     <CodeAnalysisRuleSet>$(MSBuildThisFileDirectory)/OpenTelemetry.prod.ruleset</CodeAnalysisRuleSet>
     <RunApiCompat>true</RunApiCompat>
     <ApiCompatExcludeAttributeList>$(RepoRoot)\build\GlobalAttrExclusions.txt</ApiCompatExcludeAttributeList>

build/Common.props

@@ -13,6 +13,28 @@
     <!--<AnalysisLevel>latest-All</AnalysisLevel>-->
   </PropertyGroup>
 
+  <!-- OmniSharp/VS Code requires TargetFrameworks to be in descending order for IntelliSense and analysis. -->
+  <PropertyGroup>
+    <!-- production TFMs -->
+    <TargetFrameworksForLibraries>net6.0;netstandard2.0;net462</TargetFrameworksForLibraries>
+    <TargetFrameworksForLibrariesExtended>net6.0;netstandard2.1;netstandard2.0;net462</TargetFrameworksForLibrariesExtended>
+    <TargetFrameworksForAspNetCoreInstrumentation>net7.0;net6.0;netstandard2.1;netstandard2.0</TargetFrameworksForAspNetCoreInstrumentation>
+    <TargetFrameworksForGrpcNetClientInstrumentation>net6.0;netstandard2.1;netstandard2.0</TargetFrameworksForGrpcNetClientInstrumentation>
+    <TargetFrameworksForPrometheusAspNetCore>net6.0</TargetFrameworksForPrometheusAspNetCore>
+
+    <!-- non-production TFMs -->
+    <TargetFrameworksForAspNetCoreTests>net8.0;net7.0;net6.0</TargetFrameworksForAspNetCoreTests>
+    <TargetFrameworksForAotCompatibilityTests>net8.0</TargetFrameworksForAotCompatibilityTests>
+    <TargetFrameworksForDocs>net7.0;net6.0</TargetFrameworksForDocs>
+    <TargetFrameworksForDocs Condition="$(OS) == 'Windows_NT' And '$(UsingMicrosoftNETSdkWeb)' == 'False'">
+      $(TargetFrameworksForDocs);net481;net48;net472;net471;net47;net462
+    </TargetFrameworksForDocs>
+    <TargetFrameworksForTests>net8.0;net7.0;net6.0</TargetFrameworksForTests>
+    <TargetFrameworksForTests Condition="$(OS) == 'Windows_NT'">
+      $(TargetFrameworksForTests);net462
+    </TargetFrameworksForTests>
+  </PropertyGroup>
+
   <PropertyGroup Condition="'$(Configuration)'=='Debug'">
     <DebugType>full</DebugType>
     <DebugSymbols>true</DebugSymbols>

build/docker-compose.net8.0.yml

@@ -0,0 +1,9 @@
+version: '3.7'
+
+services:
+  tests:
+    build:
+      args:
+        PUBLISH_FRAMEWORK: net8.0
+        TEST_SDK_VERSION: "8.0"
+        BUILD_SDK_VERSION: "8.0"

docs/Directory.Build.props

@@ -3,10 +3,6 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <!-- https://dotnet.microsoft.com/download/dotnet-core -->
-    <!-- OmniSharp/VS Code requires TargetFrameworks to be in descending order for IntelliSense and analysis. -->
-    <TargetFrameworks>net7.0;net6.0</TargetFrameworks>
-    <!-- https://dotnet.microsoft.com/download/dotnet-framework -->
-    <TargetFrameworks Condition="$(OS) == 'Windows_NT'">$(TargetFrameworks);net462;net47;net471;net472;net48</TargetFrameworks>
+    <TargetFrameworks>$(TargetFrameworksForDocs)</TargetFrameworks>
   </PropertyGroup>
 </Project>

docs/logs/getting-started-aspnetcore/README.md

@@ -125,6 +125,18 @@ generic `ILogger<T>` is not an option, `app.Logger` is used instead:
 app.Logger.StartingApp();
 ```
 
+> **Note**
+> There are cases where logging is needed before the [dependency injection
+(DI)](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection)
+logging pipeline is available (e.g. before `builder.Build()`) or after the DI
+logging pipeline is disposed (e.g. after `app.Run()`). The common practice is to
+use a separate logging pipeline by creating a `LoggerFactory` instance.
+>
+> Refer to the [Getting Started with OpenTelemetry .NET Logs in 5 Minutes -
+Console Application](../getting-started-console/README.md) tutorial to learn
+more about how to create a `LoggerFactory` instance and configure OpenTelemetry
+to work with it.
+
 ## Learn more
 
 * [Compile-time logging source

docs/logs/getting-started-aspnetcore/getting-started-aspnetcore.csproj

@@ -1,12 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
-
-  <PropertyGroup>
-    <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
-  </PropertyGroup>
-
   <ItemGroup>
     <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
     <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Extensions.Hosting\OpenTelemetry.Extensions.Hosting.csproj" />
   </ItemGroup>
-
 </Project>

docs/logs/getting-started-console/README.md

@@ -17,17 +17,14 @@ You should see the following output:
 Hello World!
 ```
 
-Install the latest `Microsoft.Extensions.Logging` package:
-
-  ```sh
-  dotnet add package Microsoft.Extensions.Logging
-  ```
-
-Install the
+Install the latest version of
+[Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging/)
+package and
 [OpenTelemetry.Exporter.Console](../../../src/OpenTelemetry.Exporter.Console/README.md)
 package:
 
 ```sh
+dotnet add package Microsoft.Extensions.Logging
 dotnet add package OpenTelemetry.Exporter.Console
 ```
 
@@ -73,31 +70,49 @@ Congratulations! You are now collecting logs using OpenTelemetry.
 
 What does the above program do?
 
-The program has a
+The program has created a logging pipeline by instantiating a
 [`LoggerFactory`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerfactory)
-with OpenTelemetry added as a
-[LoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers).
-This `LoggerFactory` is used to create an
+instance, with OpenTelemetry added as a [logging
+provider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers).
+OpenTelemetry SDK is then configured with a
+[ConsoleExporter](../../../src/OpenTelemetry.Exporter.Console/README.md) to
+export the logs to the console for demonstration purpose (note: ConsoleExporter
+is not intended for production usage, other exporters such as [OTLP
+Exporter](../../../src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md)
+should be used instead).
+
+The `LoggerFactory` instance is used to create an
 [`ILogger`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
-instance, which is then used to do the logging. [Compile-time logging source
-  generation](https://docs.microsoft.com/dotnet/core/extensions/logger-message-generator)
-is used to achieve structured logging and better performance. The logs are sent to
-the `OpenTelemetryLoggerProvider`, which is configured to export logs to
-`ConsoleExporter`. `ConsoleExporter` simply displays it on the console.
-
-## Note for different application types
-
-Certain types of applications (e.g. [ASP.NET
-Core](https://learn.microsoft.com/aspnet/core) and [.NET
-Worker](https://learn.microsoft.com/dotnet/core/extensions/workers)) have an
-`ILogger` based logging pipeline set up by default. In such apps, enabling
-OpenTelemetry should be done by adding OpenTelemetry as a provider to the
-*existing* logging pipeline, and users should not create a new `LoggerFactory`
-(which sets up a totally new logging pipeline). Also, obtaining `ILogger`
-instance could be done differently as well. See [Example ASP.NET Core
-application](../../../examples/AspNetCore/Program.cs) for an example which shows
-how to add OpenTelemetry to the logging pipeline already setup by the
-application.
+instance, which is used to do the actual logging.
+
+Following the .NET logging best practice, [compile-time logging source
+generation](https://docs.microsoft.com/dotnet/core/extensions/logger-message-generator)
+has been used across the example, which delivers high performance, structured
+logging, and type-checked parameters:
+
+```csharp
+public static partial class ApplicationLogs
+{
+    [LoggerMessage(EventId = 1, Level = LogLevel.Information, Message = "Food `{name}` price changed to `{price}`.")]
+    public static partial void FoodPriceChanged(this ILogger logger, string name, double price);
+
+    ...
+}
+```
+
+> **Note**
+> For applications which use `ILogger` with [dependency injection
+(DI)](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection)
+(e.g. [ASP.NET Core](https://learn.microsoft.com/aspnet/core) and [.NET
+Worker](https://learn.microsoft.com/dotnet/core/extensions/workers)), the common
+practice is to add OpenTelemetry as a [logging
+provider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers)
+to the DI logging pipeline, rather than set up a completely new logging pipeline
+by creating a new `LoggerFactory` instance.
+>
+> Refer to the [Getting Started with OpenTelemetry .NET Logs in 5 Minutes -
+ASP.NET Core Application](../getting-started-aspnetcore/README.md) tutorial to
+learn more.
 
 ## Learn more