Log correlation/redaction doc improvements (#5262)

Co-authored-by: Mikel Blanchard <[email protected]>

Author: reyang

docs/logs/README.md

@@ -153,3 +153,23 @@ instances if they are created by you.
 category name. Refer to the [.NET official
 document](https://learn.microsoft.com/dotnet/core/extensions/logging#log-category)
 to learn more.
+
+## Log Correlation
+
+In OpenTelemetry, logs are automatically correlated to traces. Check the [Log
+Correlation](./correlation/README.md) tutorial to learn more.
+
+## Log Enrichment
+
+TBD
+
+## Log Filtering
+
+Check the [Customizing OpenTelemetry .NET SDK for
+Logs](./customizing-the-sdk/README.md#log-filtering) document to learn more.
+
+## Log Redaction
+
+Logs might contain sensitive information such as passwords and credit card
+numbers, proper redaction is required to prevent privacy and security incidents.
+Check the [Log Redaction](./redaction/README.md) tutorial to learn more.

docs/logs/correlation/LoggerExtensions.cs

@@ -0,0 +1,10 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using Microsoft.Extensions.Logging;
+
+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);
+}

docs/logs/correlation/Program.cs

@@ -7,39 +7,39 @@
 using OpenTelemetry.Logs;
 using OpenTelemetry.Trace;
 
-namespace Correlation;
-
 public class Program
 {
-    private static readonly ActivitySource MyActivitySource = new(
-        "MyCompany.MyProduct.MyLibrary");
+    private static readonly ActivitySource MyActivitySource = new("MyCompany.MyProduct.MyLibrary");
 
     public static void Main()
     {
-        // Setup Logging
-        using var loggerFactory = LoggerFactory.Create(builder =>
+        var tracerProvider = Sdk.CreateTracerProviderBuilder()
+            .AddSource("MyCompany.MyProduct.MyLibrary")
+            .AddConsoleExporter()
+            .Build();
+
+        var loggerFactory = LoggerFactory.Create(builder =>
         {
-            builder.AddOpenTelemetry(options =>
+            builder.AddOpenTelemetry(logging =>
             {
-                options.AddConsoleExporter();
+                logging.AddConsoleExporter();
             });
         });
 
         var logger = loggerFactory.CreateLogger<Program>();
 
-        // Setup Traces
-        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-            .AddSource("MyCompany.MyProduct.MyLibrary")
-            .AddConsoleExporter()
-            .Build();
-
-        // Emit activity
         using (var activity = MyActivitySource.StartActivity("SayHello"))
         {
-            activity?.SetTag("foo", 1);
-
-            // Emit logs within the context of activity
-            logger.LogInformation("Hello from {name} {price}.", "tomato", 2.99);
+            // Write a log within the context of an activity
+            logger.FoodPriceChanged("artichoke", 9.99);
         }
+
+        // Dispose logger factory before the application ends.
+        // This will flush the remaining logs and shutdown the logging pipeline.
+        loggerFactory.Dispose();
+
+        // Dispose tracer provider before the application ends.
+        // This will flush the remaining spans and shutdown the tracing pipeline.
+        tracerProvider.Dispose();
     }
 }

docs/logs/correlation/README.md

@@ -1,4 +1,4 @@
-# Logs correlation
+# Log Correlation
 
 The getting started docs for [logs](../getting-started-console/README.md) and
 [traces](../../trace/getting-started-console/README.md) showed how to emit logs
@@ -27,29 +27,32 @@ of an active `Activity`. Running the application will show the following output
 on the console:
 
 ```text
-LogRecord.Timestamp:               2022-05-18T18:51:16.4348626Z
-LogRecord.TraceId:                 d7aca5b2422ed8d15f56b6a93be4537d
-LogRecord.SpanId:                  c90ac2ad41ab4d46
+LogRecord.Timestamp:               2024-01-26T17:55:39.2273475Z
+LogRecord.TraceId:                 aed89c3b250fb9d8e16ccab1a4a9bbb5
+LogRecord.SpanId:                  bd44308753200c58
 LogRecord.TraceFlags:              Recorded
-LogRecord.CategoryName:            Correlation.Program
-LogRecord.LogLevel:                Information
-LogRecord.State:                   Hello from tomato 2.99.
+LogRecord.CategoryName:            Program
+LogRecord.Severity:                Info
+LogRecord.SeverityText:            Information
+LogRecord.Body:                    Food `{name}` price changed to `{price}`.
+LogRecord.Attributes (Key:Value):
+    name: artichoke
+    price: 9.99
+    OriginalFormat (a.k.a Body): Food `{name}` price changed to `{price}`.
+LogRecord.EventId:                 344095174
+LogRecord.EventName:               FoodPriceChanged
 
-Resource associated with LogRecord:
-service.name: unknown_service:correlation
+...
 
-Activity.TraceId:          d7aca5b2422ed8d15f56b6a93be4537d
-Activity.SpanId:           c90ac2ad41ab4d46
-Activity.TraceFlags:           Recorded
+Activity.TraceId:            aed89c3b250fb9d8e16ccab1a4a9bbb5
+Activity.SpanId:             bd44308753200c58
+Activity.TraceFlags:         Recorded
 Activity.ActivitySourceName: MyCompany.MyProduct.MyLibrary
-Activity.DisplayName: SayHello
-Activity.Kind:        Internal
-Activity.StartTime:   2022-05-18T18:51:16.3427411Z
-Activity.Duration:    00:00:00.2248932
-Activity.Tags:
-    foo: 1
-Resource associated with Activity:
-    service.name: unknown_service:correlation
+Activity.DisplayName:        SayHello
+Activity.Kind:               Internal
+Activity.StartTime:          2024-01-26T17:55:39.2223849Z
+Activity.Duration:           00:00:00.0361682
+...
 ```
 
 As you can see, the `LogRecord` automatically had the `TraceId`, `SpanId` fields

docs/logs/getting-started-aspnetcore/Program.cs

@@ -39,7 +39,7 @@
 
 app.Run();
 
-public static partial class ApplicationLogs
+internal static partial class LoggerExtensions
 {
     [LoggerMessage(LogLevel.Information, "Starting the app...")]
     public static partial void StartingApp(this ILogger logger);

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

@@ -105,7 +105,7 @@ has been used across the example, which delivers high performance, structured
 logging, and type-checked parameters:
 
 ```csharp
-public static partial class ApplicationLogs
+internal static partial class LoggerExtensions
 {
     [LoggerMessage(LogLevel.Information, "Starting the app...")]
     public static partial void StartingApp(this ILogger logger);

docs/logs/getting-started-console/Program.cs

@@ -27,7 +27,7 @@
 // This will flush the remaining logs and shutdown the logging pipeline.
 loggerFactory.Dispose();
 
-public static partial class ApplicationLogs
+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);

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

@@ -88,7 +88,7 @@ has been used across the example, which delivers high performance, structured
 logging, and type-checked parameters:
 
 ```csharp
-public static partial class ApplicationLogs
+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);

docs/logs/redaction/Program.cs

@@ -22,7 +22,7 @@
 // This will flush the remaining logs and shutdown the logging pipeline.
 loggerFactory.Dispose();
 
-public static partial class ApplicationLogs
+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);