Merge pull request #985 from DuendeSoftware/mb/logging

Useful log namespaces and instructions on how to override the default log levels #723

Author: maartenba

src/content/docs/accesstokenmanagement/advanced/logging.md

@@ -0,0 +1,30 @@
+---
+title: "Logging"
+description: "Documentation for logging configuration and usage in Duende Access Token Management, including log levels and Serilog setup"
+date: 2026-01-19
+sidebar:
+  order: 50
+---
+
+Duende Access Token Management uses the standard logging facilities provided by ASP.NET Core. You generally do not need to perform any extra configuration, as it will use the logging provider you have already configured for your application.
+
+For general information on how to configure logging, setting up Serilog, and understanding log levels in Duende products, see our [Logging Fundamentals](/general/logging.md) guide.
+
+The Microsoft [documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging) has a good introduction and description of the built-in logging providers.
+
+## Log Levels
+
+You can control the log output for Duende Access Token Management specifically by configuring the `Duende.AccessTokenManagement` namespace in your logging configuration.
+For example, to enable debug logging for Access Token Management while keeping other logs at a higher level, you can modify your `appsettings.json`:
+
+```json
+// appsettings.json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Duende.AccessTokenManagement": "Debug"
+    }
+  }
+}
+```

src/content/docs/bff/diagnostics/index.md

@@ -14,10 +14,28 @@ provided by ASP.NET Core, so you don't need to do any extra configuration to ben
 including support for multiple logging providers. See the Microsoft [documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging) for a good introduction on logging.
 
 BFF follows the standard logging levels defined by the .NET logging framework, and uses the Microsoft guidelines for
-when certain log levels are used, similar to [how Duende IdentityServer uses log levels](/identityserver/diagnostics/logging.md).
+when certain log levels are used.
+
+For general information on how to configure logging in Duende products, see our [Logging Fundamentals](/general/logging.md) guide.
+
+### Configuration
 
 Logs are typically written under the `Duende.Bff` category, with more concrete categories for specific components.
 
+To get detailed logs from the BFF middleware with the `Microsoft.Extensions.Logging` framework, you can configure your `appsettings.json` to enable `Debug` level logs for the `Duende.Bff` namespace:
+
+```json
+// appsettings.json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Duende.Bff": "Debug"
+    }
+  }
+}
+```
+
 :::note[Multiple frontends]
 When using [multiple frontends and the `FrontendSelectionMiddleware`](/bff/architecture/multi-frontend.md),
 log messages are written in a log scope that contains a `frontend` property with the name of the frontend for which the

src/content/docs/general/logging.md

@@ -0,0 +1,126 @@
+---
+title: "Logging Fundamentals"
+description: "General guidance on configuring logging for Duende Software products using Microsoft.Extensions.Logging and Serilog."
+date: 2026-01-19
+sidebar:
+  order: 10
+---
+
+All Duende Software products (IdentityServer, Backend for Frontend (BFF), Access Token Management, etc.) use the standard logging facilities provided by ASP.NET Core (`Microsoft.Extensions.Logging`).
+This means they integrate seamlessly with whatever logging provider you choose for your application.
+
+This guide provides general instructions for setting up logging that apply to all our products.
+
+## Log Levels
+
+We adhere to the standard Microsoft guidelines for log levels. Understanding these levels helps you configure the appropriate verbosity for your environment.
+
+* **`Trace`**
+  * **Usage:** Extremely detailed information for troubleshooting complex issues.
+  * **Production:** **Do not enable** in production unless specifically instructed for diagnostics. May contain sensitive data (e.g., token hashes, PII).
+* **`Debug`**
+  * **Usage:** Internal flow details, useful for understanding _why_ a decision was made (e.g., policy evaluation, token validation steps).
+  * **Production:** Generally disabled in production, but safe to enable temporarily for deeper investigation.
+* **`Information`**
+  * **Usage:** High-level events tracking the general flow (e.g., "Request started", "Token issued").
+  * **Production:** Often the default level for production.
+* **`Warning`**
+  * **Usage:** Unexpected events that didn't stop the application but might require investigation (e.g., "Invalid client configuration detected").
+* **`Error`**
+  * **Usage:** Exceptions and errors that cannot be handled gracefully.
+* **`Critical`**
+  * **Usage:** Failures that require immediate attention (e.g., "Signing key not found").
+
+## Setup for Microsoft.Extensions.Logging
+
+This is the default logging provider for ASP.NET Core. If you haven't configured a third-party logger, this is what you are using.
+
+You can configure log levels in your `appsettings.json` file. To get detailed logs from Duende products, you often want to set the `Duende` namespace (or specific sub-namespaces) to `Debug`.
+
+```json
+// appsettings.json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft": "Warning",
+      "Microsoft.Hosting.Lifetime": "Information",
+      // Enable Debug logs for all Duende products
+      "Duende": "Debug"
+    }
+  }
+}
+```
+
+## Setup for Serilog
+
+[Serilog](https://serilog.net) is a popular structured logging library for .NET. We highly recommend it for its flexibility and rich sink ecosystem (Console, File, Seq, Elasticsearch, etc.).
+
+### 1. Installation
+
+Install the necessary packages:
+
+```bash
+dotnet add package Serilog.AspNetCore
+```
+
+### 2. Configuration In `Program.cs`
+
+Configure Serilog early in your application startup to capture all logs, including startup errors.
+
+```csharp
+// Program.cs
+using Serilog;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Configure Serilog
+builder.Host.UseSerilog((ctx, lc) => lc
+    .WriteTo.Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message:lj}{NewLine}{Exception}{NewLine}")
+    .Enrich.FromLogContext()
+    .ReadFrom.Configuration(ctx.Configuration));
+
+var app = builder.Build();
+
+app.UseSerilogRequestLogging(); // Optional: cleaner HTTP request logging
+
+// ... rest of your pipeline
+```
+
+### 3. Configuration In `appsettings.json`
+
+You can then control log levels via `appsettings.json`. This approach allows you to change log levels without recompiling your code.
+
+```json
+{
+  "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information",
+      "Override": {
+        "Microsoft": "Warning",
+        "Microsoft.Hosting.Lifetime": "Information",
+        "System": "Warning",
+        // Enable detailed logging for Duende products
+        "Duende": "Debug"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting Specific Products
+
+If you are debugging a specific component, you can target its namespace to reduce noise.
+
+| Product                     | Namespace                      |
+|-----------------------------|--------------------------------|
+| **IdentityServer**          | `Duende.IdentityServer`        |
+| **BFF**                     | `Duende.Bff`                   |
+| **Access Token Management** | `Duende.AccessTokenManagement` |
+
+Example `appsettings.json` for debugging only BFF interactions:
+
+```json
+"Duende.Bff": "Debug",
+"Duende.IdentityServer": "Information"
+```

src/content/docs/identitymodel-oidcclient/logging.md

@@ -11,7 +11,11 @@ redirect_from:
 `OidcClient` logs errors, warnings, and diagnostic information using
 `Microsoft.Extensions.Logging.ILogger`, the standard .NET logging library.
 
-```csharp
+You can use any logging provider to store your logs however you like,
+by setting the `LoggerFactory` property on `OidcClientOptions`:
+
+```csharp {9,17}
+// Program.cs
 using Duende.IdentityModel;
 using Duende.IdentityModel.OidcClient;
 
@@ -36,20 +40,9 @@ var app = builder.Build();
 var client = app.Services.GetService<OidcClient>();
 ```
 
-You can use any logging provider to store your logs however you like, by setting the `LoggerFactory` property on `OidcClientOptions`.
-
-For example, you could configure
-[Serilog](https://github.com/serilog/serilog-extensions-hosting) like this:
+Using this approach, you can use other logging frameworks, like [Serilog](https://github.com/serilog/serilog-extensions-hosting) for example.
 
-```csharp
-var serilog = new LoggerConfiguration()
-    .MinimumLevel.Verbose()
-    .Enrich.FromLogContext()
-    .WriteTo.LiterateConsole(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message}{NewLine}{Exception}{NewLine}")
-    .CreateLogger();
-
-options.LoggerFactory.AddSerilog(serilog);
-```
+For general information on how to configure logging in .NET applications, see our [Logging Fundamentals](/general/logging.md) guide.
 
 ## Log Levels
 
@@ -63,6 +56,7 @@ The `OidcClient` logs at the following levels:
 You can set the log level in your `appsettings.json` by modifying the following snippet.
 
 ```json
+// appsettings.json
 {
   "Logging": {
     "LogLevel": {