Edit

Share via


ASP.NET Core Blazor WebAssembly Event Pipe diagnostics

This article describes Event Pipe diagnostic tools, counters, and how to get a Garbage Collector heap dump in Blazor WebAssembly apps.

Prerequisite

Install the .NET WebAssembly build tools:

dotnet workload install wasm-tools

.NET Core Diagnostics Client Library example

Parse and validate NetTrace (.nettrace) messages using the .NET Core Diagnostics Client Library:

For more information, see the .NET Core diagnostics documentation and the IpcMessage API (reference source).

Note

Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).

The MSBuild properties in the following table enable profiler integration.

Property Default Set value to… Description
<WasmPerfTracing> false true Controls diagnostic server tracing.
<MetricsSupport> false true Controls System.Diagnostics.Metrics support. For more information, see the System.Diagnostics.Metrics namespace.
<EventSourceSupport> false true Controls EventPipe support. For more information, see Diagnostics and instrumentation: Observability and telemetry.

Enabling profilers has negative size and performance impact, so don't publish an app for production with profilers enabled. In the following example, a condition is set on a property group section that only enables profiling when the app is built with /p:BlazorSampleProfilingEnabled=true (.NET CLI) or <BlazorSampleProfilingEnabled>true</BlazorSampleProfilingEnabled> in a Visual Studio publish profile, where "BlazorSampleProfilingEnabled" is a custom symbol name that you choose and doesn't conflict with other symbol names.

In the app's project file (.csproj):

<PropertyGroup Condition="'$(BlazorSampleProfilingEnabled)' == 'true'">
  <WasmPerfTracing>true</WasmPerfTracing>
  <MetricsSupport>true</MetricsSupport>
  <EventSourceSupport>true</EventSourceSupport>
</PropertyGroup>

Alternatively, enable features when the app is built with the .NET CLI. The following options passed to the dotnet build command mirror the preceding MS Build property configuration:

/p:WasmPerfTracing=true /p:WasmPerfInstrumentation=true /p:MetricsSupport=true /p:EventSourceSupport=true

The Timing-Allow-Origin HTTP header allows for more precise time measurements.

EventPipe profiler

EventPipe is a runtime component used to collect tracing data, similar to ETW and perf_events.

Use the <WasmPerfInstrumentation> property to enable CPU sampling instrumentation for diagnostic server. This setting isn't necessary for memory dump or counters. Makes the app execute slower. Only set this to true for performance profiling.

Enabling profilers has negative size and performance impact, so don't publish an app for production with profilers enabled. In the following example, a condition is set on a property group section that only enables profiling when the app is built with /p:BlazorSampleProfilingEnabled=true (.NET CLI) or <BlazorSampleProfilingEnabled>true</BlazorSampleProfilingEnabled> in a Visual Studio publish profile, where "BlazorSampleProfilingEnabled" is a custom symbol name that you choose and doesn't conflict with other symbol names.

<PropertyGroup Condition="'$(BlazorSampleProfilingEnabled)' == 'true'">
  <WasmPerfInstrumentation>true</WasmPerfInstrumentation>
</PropertyGroup>

Collect CPU counters for 60 seconds with collectCpuSamples(durationSeconds):

globalThis.getDotnetRuntime(0).collectCpuSamples({durationSeconds: 60});

To view the trace, see Use EventPipe to trace your .NET application.

GC (Garbage Collector) dumps

The dotnet-gcdump (collect/convert` options) global tool collects GC (Garbage Collector) dumps of live .NET processes using EventPipe.

Collect a GC (Garbage Collector) dump of the live .NET process with collectGcDump:

globalThis.getDotnetRuntime(0).collectGcDump();

To view the captured GC dump, see View the GC dump captured from dotnet-gcdump.

Counters trace

dotnet-counters collect is a performance monitoring tool for ad-hoc health monitoring and first-level performance investigation.

Collect diagnostic counters for 60 seconds with collectPerfCounters(durationSeconds):

globalThis.getDotnetRuntime(0).collectPerfCounters({durationSeconds: 60});

To view the trace, see Use EventPipe to trace your .NET application.

Additional resources