[API Proposal] Diagnostic traces for Blazor

[pavelsavara]

Background and Motivation

In Net10 we are adding new diagnostic traces for Blazor. This is not C# API but about OTEL names.

Implementation is in #61609 and #62286

There was already feedback about names in both implementation PRs
There is also feedback in external OTEL repo that guides the naming conventions open-telemetry/semantic-conventions#2235

Proposed API

new source Microsoft.AspNetCore.Components

• Trace name: Microsoft.AspNetCore.Components.RouteChange
  • Description: User navigated to new Blazor route/page
  • Tag: aspnetcore.components.type - class name of the Page component
  • Tag: aspnetcore.components.route - URL path pattern of the Blazor page
  • Tag: error.type - exception type full name, optional
  • Link: HTTP trace
  • Link: SignalR trace
  • Link: Circuit trace
  • Usage: which Blazor pages this session visited ?
• Trace name: Microsoft.AspNetCore.Components.HandleEvent
  • Description: User interacted with the component
  • Tag: aspnetcore.components.type - full name of target C# component that receives the event
  • Tag: aspnetcore.components.method - C# method name of the handler
  • Tag: aspnetcore.components.attribute.name - name of the HTML attribute that triggers the event, i.e. onClick
  • Tag: error.type - exception type full name, optional
  • Link: HTTP trace
  • Link: SignalR trace
  • Link: Circuit trace
  • Link: Route trace
  • Usage: click to which component caused exception ? On which page ?
  • Usage: in which linked circuit and with what HTTP context it happened ?

new source Microsoft.AspNetCore.Components.Server.Circuits

• Trace name: Microsoft.AspNetCore.Components.Server.Circuits.CircuitStart
  • Description: User navigated to interactive server Blazor page
  • Tag: aspnetcore.components.circuit.id - class name of the Page component
  • Tag: error.type - exception type full name, optional
  • Link: HTTP trace
  • Link: SignalR trace
  • Usage: links other Blazor traces of the same session/circuit to HTTP and SignalR contexts

Usage Examples

builder.Services.ConfigureOpenTelemetryTracerProvider(tracerProvider =>
{
    tracerProvider.AddSource("Microsoft.AspNetCore.Components");
    tracerProvider.AddSource("Microsoft.AspNetCore.Components.Server.Circuits");
});

Alternative Designs

• OTEL feedback was that they don't use plurals in names and that our namespace aspnetcore.components is breaking that rule.
  • I prefer to stick to existing .NET namespace.

Risks

Small perf impact when enabled/subscribed to.

[pavelsavara]

cc @noahfalk @JamesNK @samsp-msft @danroth27 @javiercn @lewing @BrennanConroy @lmolkova this is to catch up with more formal API review on the OTEL names for new Blazor traces

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.