From aeca53949a742aa270e9c94d5a53c6a1821a6802 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 28 Sep 2023 16:53:33 -0700 Subject: [PATCH] Improve the logging tutorial by clarifying DI vs. exlicit logging pipeline (#4897) --- .../logs/getting-started-aspnetcore/README.md | 12 +++++++++ docs/logs/getting-started-console/README.md | 26 +++++++++---------- .../README.md | 10 +++---- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/docs/logs/getting-started-aspnetcore/README.md b/docs/logs/getting-started-aspnetcore/README.md index 81b5407ee..bce211dc8 100644 --- a/docs/logs/getting-started-aspnetcore/README.md +++ b/docs/logs/getting-started-aspnetcore/README.md @@ -125,6 +125,18 @@ generic `ILogger` 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 diff --git a/docs/logs/getting-started-console/README.md b/docs/logs/getting-started-console/README.md index 8248ddf03..380eccfb7 100644 --- a/docs/logs/getting-started-console/README.md +++ b/docs/logs/getting-started-console/README.md @@ -85,19 +85,19 @@ is used to achieve structured logging and better performance. The logs are sent 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. +> **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 diff --git a/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md b/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md index 568370008..183df4498 100644 --- a/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md +++ b/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md @@ -75,12 +75,10 @@ customize the `LogRecordExportProcessorOptions` or see the [Environment Variables](#environment-variables) section below on how to customize using environment variables. -> **Note** For details on how to configure logging with OpenTelemetry check this -> [console](../../docs/logs/getting-started-console/Program.cs) or [ASP.NET -Core](../../examples/AspNetCore/Program.cs) example app. Check this -**[section](../../docs/logs/getting-started-console/readme.md#note-for-different-application-types)** -for configuring OpenTelemetry with `ILogger` for certain application types such -as ASP.NET Core and .NET Worker. +> **Note** +> For details on how to configure logging with OpenTelemetry check the +[Console](../../docs/logs/getting-started-console/README.md) or [ASP.NET +Core](../../docs/logs/getting-started-aspnetcore/README.md) tutorial. **ILogger Scopes**: OTLP Log Exporter supports exporting `ILogger` scopes as Attributes. Scopes must be enabled at the SDK level using