[docs-logging] Add a logging doc for showing how to set up a dedicate…

…d pipeline for specific logs (#5356)

OpenTelemetry.sln

@@ -340,6 +340,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "resources", "resources", "{
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "extending-the-sdk", "docs\resources\extending-the-sdk\extending-the-sdk.csproj", "{7BE494FC-4B0D-4340-A62A-9C9F3E7389FE}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dedicated-pipeline", "docs\logs\dedicated-pipeline\dedicated-pipeline.csproj", "{19545B37-8518-4BDD-AD49-00C031FB3C2A}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -626,6 +628,10 @@ Global
 		{7BE494FC-4B0D-4340-A62A-9C9F3E7389FE}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7BE494FC-4B0D-4340-A62A-9C9F3E7389FE}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{7BE494FC-4B0D-4340-A62A-9C9F3E7389FE}.Release|Any CPU.Build.0 = Release|Any CPU
+		{19545B37-8518-4BDD-AD49-00C031FB3C2A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{19545B37-8518-4BDD-AD49-00C031FB3C2A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{19545B37-8518-4BDD-AD49-00C031FB3C2A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{19545B37-8518-4BDD-AD49-00C031FB3C2A}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -680,6 +686,7 @@ Global
 		{17A22B0E-6EC3-4A39-B955-0A486AD06699} = {52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}
 		{A115CE4C-71A8-4B95-96A5-C1DF46FD94C2} = {7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}
 		{7BE494FC-4B0D-4340-A62A-9C9F3E7389FE} = {A115CE4C-71A8-4B95-96A5-C1DF46FD94C2}
+		{19545B37-8518-4BDD-AD49-00C031FB3C2A} = {3862190B-E2C5-418E-AFDC-DB281FB5C705}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}

docs/logs/dedicated-pipeline/DedicatedLogging/DedicatedLoggingServiceCollectionExtensions.cs

@@ -0,0 +1,73 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using OpenTelemetry.Logs;
+
+namespace DedicatedLogging;
+
+public static class DedicatedLoggingServiceCollectionExtensions
+{
+    public static IServiceCollection AddDedicatedLogging(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        Action<OpenTelemetryLoggerOptions> configureOpenTelemetry)
+    {
+        ArgumentNullException.ThrowIfNull(configureOpenTelemetry);
+
+        services.TryAddSingleton(sp =>
+        {
+            var loggerFactory = LoggerFactory.Create(builder =>
+            {
+                builder.AddConfiguration(configuration);
+
+                builder.AddOpenTelemetry(configureOpenTelemetry);
+            });
+
+            return new DedicatedLoggerFactory(loggerFactory);
+        });
+
+        services.TryAdd(ServiceDescriptor.Singleton(typeof(IDedicatedLogger<>), typeof(DedicatedLogger<>)));
+
+        return services;
+    }
+
+    private sealed class DedicatedLogger<T> : IDedicatedLogger<T>
+    {
+        private readonly ILogger innerLogger;
+
+        public DedicatedLogger(DedicatedLoggerFactory loggerFactory)
+        {
+            this.innerLogger = loggerFactory.CreateLogger(typeof(T).FullName!);
+        }
+
+        public IDisposable? BeginScope<TState>(TState state)
+            where TState : notnull
+            => this.innerLogger.BeginScope(state);
+
+        public bool IsEnabled(LogLevel logLevel)
+            => this.innerLogger.IsEnabled(logLevel);
+
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
+            => this.innerLogger.Log(logLevel, eventId, state, exception, formatter);
+    }
+
+    private sealed class DedicatedLoggerFactory : ILoggerFactory
+    {
+        private readonly ILoggerFactory innerLoggerFactory;
+
+        public DedicatedLoggerFactory(ILoggerFactory loggerFactory)
+        {
+            this.innerLoggerFactory = loggerFactory;
+        }
+
+        public void AddProvider(ILoggerProvider provider)
+            => this.innerLoggerFactory.AddProvider(provider);
+
+        public ILogger CreateLogger(string categoryName)
+            => this.innerLoggerFactory.CreateLogger(categoryName);
+
+        public void Dispose()
+            => this.innerLoggerFactory.Dispose();
+    }
+}

docs/logs/dedicated-pipeline/DedicatedLogging/IDedicatedLogger.cs

@@ -0,0 +1,12 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+namespace DedicatedLogging;
+
+public interface IDedicatedLogger : ILogger
+{
+}
+
+public interface IDedicatedLogger<out TCategoryName> : IDedicatedLogger
+{
+}

docs/logs/dedicated-pipeline/Program.cs

@@ -0,0 +1,47 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using DedicatedLogging;
+using OpenTelemetry.Logs;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Logging.ClearProviders();
+
+builder.Logging.AddOpenTelemetry(options =>
+{
+    // Set up primary pipeline for common app logs
+    options.AddConsoleExporter();
+});
+
+builder.Services.AddDedicatedLogging(
+    builder.Configuration.GetSection("DedicatedLogging"), // Bind configuration for dedicated logging pipeline
+    options =>
+    {
+        // Set up secondary pipeline for dedicated logs
+        options.AddConsoleExporter();
+    });
+
+var app = builder.Build();
+
+app.MapGet("/", (HttpContext context, ILogger<Program> logger, IDedicatedLogger<Program> dedicatedLogger) =>
+{
+    // Standard log written
+    logger.FoodPriceChanged("artichoke", 9.99);
+
+    // Dedicated log written
+    dedicatedLogger.RequestInitiated(context.Connection.RemoteIpAddress?.ToString() ?? "unknown");
+
+    return "Hello from OpenTelemetry Logs!";
+});
+
+app.Run();
+
+internal static partial class LoggerExtensions
+{
+    [LoggerMessage(LogLevel.Information, "Food `{name}` price changed to `{price}`.")]
+    public static partial void FoodPriceChanged(this ILogger logger, string name, double price);
+
+    [LoggerMessage(LogLevel.Information, "Request initiated from `{ipAddress}`.")]
+    public static partial void RequestInitiated(this IDedicatedLogger logger, string ipAddress);
+}

docs/logs/dedicated-pipeline/README.md

@@ -0,0 +1,4 @@
+# Dedicated pipeline
+
+This example shows how to create a dedicated logging pipeline for specific logs
+which will be sent to a different location than normal application logs.

docs/logs/dedicated-pipeline/appsettings.Development.json

@@ -0,0 +1,9 @@
+{
+  "DetailedErrors": true,
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/logs/dedicated-pipeline/appsettings.json

@@ -0,0 +1,14 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "DedicatedLogging": {
+    "LogLevel": {
+      "Default": "Information"
+    }
+  },
+  "AllowedHosts": "*"
+}

docs/logs/dedicated-pipeline/dedicated-pipeline.csproj

@@ -0,0 +1,6 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <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>