Merge pull request #1002 from DuendeSoftware/ar/logs-to-otel

Add Logs info to OTel docs

Author: ProgrammerAL

src/content/docs/identityserver/diagnostics/images/aspire_structured_logs.png

@@ -114,3 +114,7 @@ var isBuilder = builder.Services.AddIdentityServer(options =>
 ```
 
 Returning `true` means the exception will be logged, while returning `false` indicates the exception should not be logged.
+
+## OpenTelemetry
+
+Logs written to the standard `ILogger` system in .NET 8+ can be exported to OpenTelemetry traces at runtime. This helps visualize when the log statement occurred in relation to the entire request. The logs are augmented with trace ids and correlated with traces. Have a look at [logs in OpenTelemetry](/identityserver/diagnostics/otel.md#logs) for setup details.

src/content/docs/identityserver/diagnostics/images/aspire_structured_logs_in_trace.png

@@ -19,20 +19,20 @@ redirect_from:
 Added in Duende IdentityServer v6.1 and expanded in v7.0
 :::
 
-[OpenTelemetry](https://opentelemetry.io) is a collection of tools, APIs, and SDKs for generating and collecting
+[OpenTelemetry](https://opentelemetry.io) (OTel) is a collection of tools, APIs, and SDKs for generating and collecting
 telemetry data (metrics, logs, and traces). This is very useful for analyzing software performance and behavior,
 especially in highly distributed systems.
 
-.NET 8 comes with first class support for OpenTelemetry. IdentityServer emits traces, metrics, and logs.
 
-### Metrics
+## OpenTelemetry Signals
 
-Metrics are high level statistic counters. They provide an aggregated overview and can be used to set monitoring rules.
+OpenTelemetry signals are the information collected and processed to describe the internal activity of the system. The most common signals are traces, metrics, and logs.
 
-### Logs
+.NET 8+ comes with first class support for OpenTelemetry. IdentityServer emits traces, metrics, and logs you can collect.
 
-OpenTelemetry in .NET 8 exports the logs written to the standard ILogger system. The logs are augmented with
-trace ids to be able to correlate log entries with traces.
+### Metrics
+
+Metrics are high level statistic counters. They provide an aggregated overview and can be used to set monitoring rules.
 
 ### Traces
 
@@ -45,20 +45,47 @@ IdentityServer to get a new access token and then calls the API. The API reads t
 url and then gets the keys from jwks endpoint.
 ![.NET Aspire dashboard showing Duende IdentityServer traces](images/aspire_traces.png)
 
+### Logs
+
+OpenTelemetry in .NET 8+ can export logs written to the standard `ILogger` system. The logs are augmented with
+trace ids and correlated with traces.
+
+This is an example of a structured log message from a web application calling an API (also displayed using our
+[Aspire sample](/identityserver/samples/diagnostics.mdx)).
+
+![.NET Aspire dashboard showing Duende IdentityServer Structured Logs](images/aspire_structured_logs.png)
+
+Here is an example of that same log message appearing in the trace. Aspire displays the log entry details as dots on the trace timeline.
+
+![.NET Aspire dashboard showing Duende IdentityServer a trace with a log entry](images/aspire_structured_logs_in_trace.png)
+
 ## Setup
 
 To start emitting OpenTelemetry tracing and metrics information you need to:
 
 * add the OpenTelemetry libraries to your IdentityServer and client applications
-* start collecting traces and Metrics from the various IdentityServer sources (and other sources e.g. ASP.NET Core)
+* start collecting traces and metrics from the various IdentityServer sources (and other sources e.g. ASP.NET Core)
+* add the OpenTelemetry configuration to your service setup
 
 For development a simple option is to export the tracing information to the console and use the Prometheus
 exporter to create a human-readable `/metrics` endpoint for the metrics.
 
-Add the OpenTelemetry configuration to your service setup.
+```bash
+dotnet add package OpenTelemetry
+dotnet add package OpenTelemetry.Extensions.Hosting
+dotnet add package OpenTelemetry.Instrumentation.AspNetCore
+dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
+```
 
 ```csharp
 // Program.cs
+using OpenTelemetry.Resources;
+
+// Add OpenTelemetry logging infrastructure
+// to correlate logs with traces
+builder.Logging.AddOpenTelemetry();
+
+// Enable OpenTelemetry
 var openTelemetry = builder.Services.AddOpenTelemetry();
 
 openTelemetry.ConfigureResource(r => r
@@ -432,3 +459,27 @@ You can select which information you are interested in by selectively listening
 * *`IdentityServerConstants.Tracing.Validation`*
 
   More detailed tracing related to validation
+
+## OpenTelemetry From 3rd Party Logging Frameworks
+
+If you're unable to use the `ILogger` system in .NET, your choice of logging framework may be able to push log messages to traces. You can view their documentation to set that up.
+
+### OpenTelemetry with Serilog
+
+If you are logging with Serilog and want to use that framework's native API to push log messages to traces, you need to:
+
+* Add the Serilog OpenTelemetry sink library
+* Instruct the Serilog logger object to write to the OpenTelemetry sink
+
+Note: See the Serilog [OpenTelemetry sink](https://github.com/serilog/serilog-sinks-opentelemetry) documentation for the most up to date information.
+
+```bash
+dotnet add package Serilog.Sinks.OpenTelemetry
+```
+
+```csharp {2}
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.OpenTelemetry()
+    .CreateLogger();
+```
+