From 3fb2ec50d0370dbe52ab216cfe898a8086040a8b Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 26 Jan 2024 13:45:25 -0800 Subject: [PATCH] Log correlation/redaction doc improvements (#5262) Co-authored-by: Mikel Blanchard --- docs/logs/README.md | 20 +++++++++ docs/logs/correlation/LoggerExtensions.cs | 10 +++++ docs/logs/correlation/Program.cs | 38 ++++++++-------- docs/logs/correlation/README.md | 43 ++++++++++--------- .../getting-started-aspnetcore/Program.cs | 2 +- .../logs/getting-started-aspnetcore/README.md | 2 +- docs/logs/getting-started-console/Program.cs | 2 +- docs/logs/getting-started-console/README.md | 2 +- docs/logs/redaction/Program.cs | 2 +- 9 files changed, 77 insertions(+), 44 deletions(-) create mode 100644 docs/logs/correlation/LoggerExtensions.cs diff --git a/docs/logs/README.md b/docs/logs/README.md index 8047b1170c6..2c456035431 100644 --- a/docs/logs/README.md +++ b/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. diff --git a/docs/logs/correlation/LoggerExtensions.cs b/docs/logs/correlation/LoggerExtensions.cs new file mode 100644 index 00000000000..facd6d895c8 --- /dev/null +++ b/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); +} diff --git a/docs/logs/correlation/Program.cs b/docs/logs/correlation/Program.cs index 9813e514c99..b1a3284fbcc 100644 --- a/docs/logs/correlation/Program.cs +++ b/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(); - // 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(); } } diff --git a/docs/logs/correlation/README.md b/docs/logs/correlation/README.md index 0c8b0ce5e4a..309cfea64d0 100644 --- a/docs/logs/correlation/README.md +++ b/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 diff --git a/docs/logs/getting-started-aspnetcore/Program.cs b/docs/logs/getting-started-aspnetcore/Program.cs index 60d332c3a8a..179d9d2237a 100644 --- a/docs/logs/getting-started-aspnetcore/Program.cs +++ b/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); diff --git a/docs/logs/getting-started-aspnetcore/README.md b/docs/logs/getting-started-aspnetcore/README.md index 1a4b8717485..6c6bbe26dc2 100644 --- a/docs/logs/getting-started-aspnetcore/README.md +++ b/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); diff --git a/docs/logs/getting-started-console/Program.cs b/docs/logs/getting-started-console/Program.cs index cb7c075ab17..b907d169d20 100644 --- a/docs/logs/getting-started-console/Program.cs +++ b/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); diff --git a/docs/logs/getting-started-console/README.md b/docs/logs/getting-started-console/README.md index 7cd60b47bc1..aa251d09951 100644 --- a/docs/logs/getting-started-console/README.md +++ b/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); diff --git a/docs/logs/redaction/Program.cs b/docs/logs/redaction/Program.cs index 207a2b659d5..fa33d884581 100644 --- a/docs/logs/redaction/Program.cs +++ b/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);