Blazor Web App

Install

One package, referenced by the project that renders App.razor (the server) and by the client project when there is one. It brings the browser script with it as a static web asset, at _content/Bit.Belemetry/bit-belemetry.js.

dotnet add package Bit.Belemetry

Register in both projects

Call AddBitBelemetryServices in the server's Program.cs and in the client's. Every component is instantiated twice - once on the server for the prerender pass and again in the browser - so whatever a page injects (IBelemetry, IBelemetryConsent) has to resolve in both containers. The call is idempotent and follows the Options pattern: every configure callback, across calls, runs in order on the same BelemetryOptions, which makes a shared configuration method the natural way to keep the two in step.

// In the client project, so both Program.cs files can call it.
using Bit.Belemetry;

public static class AppTelemetry
{
    public static void Configure(BelemetryOptions options)
    {
        options.ServiceName = "MyApp";
        options.AddOtlpExporter("https://otel.example.com");

        options.Consent.Default = BelemetryFeatures.None;   // opt-in until the user decides

        options.Traces.Sources.Add("MyApp*");
        options.Metrics.Meters.Add("MyApp");
    }
}

// Server/Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

builder.Services.AddBitBelemetryServices(options =>
{
    AppTelemetry.Configure(options);
    options.Environment = builder.Environment.EnvironmentName;
});

// Client/Program.cs
var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Services.AddBitBelemetryServices(options =>
{
    AppTelemetry.Configure(options);
    options.Environment = builder.HostEnvironment.Environment;
});

await builder.Build().RunAsync();

Each container has its own job:

The script in App.razor

<BelemetryScript /> renders the configuration as an inline JSON element and the module after it. Because it is static markup in the head, the script starts before Blazor boots - it sees the initial page view, the web vitals and errors thrown while the runtime downloads - and it also covers static SSR pages that never become interactive.

@* Server/Components/App.razor *@
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <base href="/" />
    <BelemetryScript />
    <HeadOutlet @rendermode="InteractiveAuto" />
</head>
<body>
    <Routes @rendermode="InteractiveAuto" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

The initializer in Routes.razor

<BelemetryInitializer /> connects the script to .NET once the app is interactive: consent and the session flow both ways, browser records can be relayed to .NET, and the WebAssembly pipeline gets its unload flush. It renders nothing. Place it once, in Routes.razor or the main layout, inside the interactive part of the app.

@* Client/Routes.razor *@
<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
    </Found>
</Router>

<BelemetryInitializer />

Per render mode

The setup above does not change between render modes. What changes is where .NET telemetry is collected and how IBelemetry calls travel:

On a static SSR page there is no circuit and no WebAssembly runtime, so IBelemetryConsent has nobody to talk to. The script is still running, and a plain HTML banner can record the choice with its JavaScript API - the same bit-belemetry-consent entry the .NET API writes, so an interactive page later reads the same decision:

The server pipeline

On an ASP.NET Core host Belemetry's .NET pipeline is off by default - such hosts usually have an OpenTelemetry setup of their own - and the server registration only renders and serves the script. Turn it on to collect the server's logs, traces (including the Microsoft.AspNetCore request spans) and metrics with the same exporters. It is process-wide, serving every user at once, so it follows Server.Features - an operator decision - and not any one user's consent. With Server and Auto, this is also where an interactive circuit's ILogger output is collected.

builder.Services.AddBitBelemetryServices(options =>
{
    AppTelemetry.Configure(options);

    options.Server.CollectDotnetTelemetry = true;
    options.Server.Features = BelemetryFeatures.Errors | BelemetryFeatures.Logs
                            | BelemetryFeatures.Traces | BelemetryFeatures.Metrics;   // the default
});

Browser fetch spans add a traceparent to same-origin requests, so the server's request span becomes a child of the browser's span and the two land in one trace. More on the Server pipeline page.

What this site does

This documentation site is a Blazor Web App in the InteractiveWebAssembly render mode, prerendered, and it is set up exactly as above: AddBitBelemetryServices in both projects through a shared DemoTelemetry.ConfigureShared, <BelemetryScript /> in App.razor, <BelemetryInitializer /> in Routes.razor, and the server pipeline turned on. It exports OTLP/JSON to itself, and an in-process receiver hands each reader their own records back.

API