Merge pull request #951 from DuendeSoftware/mb/bff-otel

BFF v4 - OpenTelemetry docs

Author: maartenba

.idea/compiler.xml

@@ -0,0 +1,3 @@
+label: "Diagnostics"
+collapsed: true
+order: 5

src/content/docs/bff/diagnostics/_meta.yml

@@ -0,0 +1,74 @@
+---
+title: "Diagnostics"
+description: Overview of Duende Backend for Frontend (BFF) diagnostic capabilities including logging and OpenTelemetry integration to assist with monitoring and troubleshooting
+date: 2025-11-27T08:20:20+02:00
+sidebar:
+  label: Overview
+  order: 1
+---
+
+## Logging
+
+Duende Backend for Frontend (BFF) offers several diagnostics possibilities. It uses the standard logging facilities
+provided by ASP.NET Core, so you don't need to do any extra configuration to benefit from rich logging functionality,
+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).
+
+Logs are typically written under the `Duende.Bff` category, with more concrete categories for specific components.
+
+:::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
+log message was emitted.
+:::
+
+## OpenTelemetry :badge[v4.0]
+
+OpenTelemetry provides a single standard for collecting and exporting telemetry data, such as metrics, logs, and traces.
+
+To start emitting OpenTelemetry data in Duende Backend for Frontend (BFF), you need to:
+
+* add the OpenTelemetry libraries to your BFF host and client applications
+* start collecting traces and metrics from the various BFF sources (and other sources such as ASP.NET Core, the `HttpClient`, etc.)
+
+The following configuration adds the OpenTelemetry configuration to your service setup, and exports data to an [OTLP exporter](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/observability-with-otel):
+
+```cs
+// Program.cs
+var openTelemetry = builder.Services.AddOpenTelemetry();
+
+openTelemetry.ConfigureResource(r => r
+    .AddService(builder.Environment.ApplicationName));
+
+openTelemetry.WithMetrics(metrics =>
+    {
+        metrics.AddAspNetCoreInstrumentation()
+            .AddHttpClientInstrumentation()
+            .AddRuntimeInstrumentation()
+            .AddMeter(BffMetrics.MeterName);
+    });
+
+openTelemetry.WithTracing(tracing =>
+    {
+        tracing.AddSource(builder.Environment.ApplicationName)
+            .AddAspNetCoreInstrumentation()
+            // Uncomment the following line to enable gRPC instrumentation
+            // (requires the OpenTelemetry.Instrumentation.GrpcNetClient package)
+            //.AddGrpcClientInstrumentation()
+            .AddHttpClientInstrumentation();
+    });
+
+openTelemetry.UseOtlpExporter();
+```
+
+## Metrics
+
+OpenTelemetry metrics are run-time measurements are typically used to show graphs on a dashboard, to inspect overall
+application health, or to set up monitoring rules.
+
+The BFF host emits metrics from several sources, and collects these through the `Duende.Bff` meter:
+
+* `session.started` - a counter that communicates the number of sessions started
+* `session.ended` - a counter that communicates the number of sessions ended

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

@@ -1,3 +1,3 @@
 label: "Samples"
-order: 5
+order: 6
 collapsed: true

src/content/docs/bff/samples/_meta.yml

@@ -33,7 +33,7 @@ economical option that is a good fit for organizations with basic needs. It's al
 choice if you have an aging IdentityServer4 implementation that needs to be updated and
 licensed. The Starter edition includes all the features that were part of
 IdentityServer4, along with support for the latest .NET releases, improved observability
-through OTEL support, and years of bug fixes and enhancements.
+through OpenTelemetry support, and years of bug fixes and enhancements.
 
 ### Business Edition
 

src/content/docs/general/licensing.md

@@ -19,9 +19,9 @@ to the UI/client are very brief - the logs always have all the details of what w
 
 [Read More](/identityserver/diagnostics/logging.md)
 
-## Open Telemetry
+## OpenTelemetry
 
-Open Telemetry is the new standard way of emitting diagnostics information from a process and
+OpenTelemetry is a standard way of emitting diagnostics information from a process and
 IdentityServer supports Traces (.NET Activities), Metrics and Logs.
 
 [Read More](/identityserver/diagnostics/otel.md)
@@ -30,7 +30,7 @@ IdentityServer supports Traces (.NET Activities), Metrics and Logs.
 
 The eventing system was created as an extension point to integrate with application monitoring
 systems (APM). They used to have their own different APIs so IdentityServer only provided events
-that could be used to call the APM's APIs. Thanks to Open Telemetry there is now a standardized
+that could be used to call the APM's APIs. Thanks to OpenTelemetry there is now a standardized
 way to emit diagnostic information from a process. The events may eventually be deprecated and removed.
 
 [Read More](/identityserver/diagnostics/events.md)

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

@@ -23,7 +23,7 @@ Added in Duende IdentityServer v6.1 and expanded in v7.0
 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 Open Telemetry. IdentityServer emits traces, metrics, and logs.
+.NET 8 comes with first class support for OpenTelemetry. IdentityServer emits traces, metrics, and logs.
 
 ### Metrics
 
@@ -47,15 +47,15 @@ url and then gets the keys from jwks endpoint.
 
 ## Setup
 
-To start emitting Otel tracing and metrics information you need
+To start emitting OpenTelemetry tracing and metrics information you need to:
 
-* add the Otel libraries to your IdentityServer and client applications
+* 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)
 
 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 Open Telemetry configuration to your service setup.
+Add the OpenTelemetry configuration to your service setup.
 
 ```cs
 // Program.cs
@@ -83,7 +83,7 @@ Add the Prometheus exporter to the pipeline
 
 ```cs
 // Program.cs
-// Map /metrics that displays Otel data in human-readable form.
+// Map /metrics that displays OpenTelemetry data in human-readable form.
 app.UseOpenTelemetryPrometheusScrapingEndpoint();
 ```
 
@@ -97,7 +97,7 @@ Added in Duende IdentityServer v7.0
 
 OpenTelemetry metrics are run-time measurements that are intended to provide an indication
 of overall health and are typically used to show graphs on a dashboard or to set up monitoring rules.
-When that monitoring reveals issues, traces and logs are used to investigate further. Open Telemetry monitoring
+When that monitoring reveals issues, traces and logs are used to investigate further. OpenTelemetry monitoring
 tools often provide features to find the traces and logs corresponding to certain metrics.
 
 IdentityServer emits metrics from the IdentityServer middleware and services. Our quick start for the UI also
@@ -391,7 +391,7 @@ Here's e.g. the output for a request to the discovery endpoint:
 
 ![Honeycomb UI showing traces for discovery document endpoint](images/otel_disco.png)
 
-When multiple applications send their traces to the same OTel server, this becomes super useful for following e.g.
+When multiple applications send their traces to the same OpenTelemetry server, this becomes super useful for following e.g.
 authentication flows over service boundaries.
 
 The following screenshot shows the ASP.NET Core OpenID Connect authentication handler redeeming the authorization code: