startup-perf - SKILL.md Agent Skill

name: startup-perf description: Measures Aspire application startup performance using dotnet-trace and the TraceAnalyzer tool. Use this when asked to measure impact of a code change on Aspire application startup performance.

Aspire Startup Performance Measurement

This skill provides patterns and practices for measuring .NET Aspire application startup performance using the Measure-StartupPerformance.ps1 (Windows/PowerShell) or measure-startup-performance.sh (macOS/Linux) script and the companion TraceAnalyzer tool.

Overview

The startup performance tooling collects dotnet-trace traces from an Aspire AppHost application and computes the startup duration from AspireEventSource events. Specifically, it measures the time between the DcpModelCreationStart (event ID 17) and DcpModelCreationStop (event ID 18) events emitted by the Microsoft-Aspire-Hosting EventSource provider.

PowerShell Script (Windows): tools/perf/Measure-StartupPerformance.ps1 Bash Script (macOS/Linux): tools/perf/measure-startup-performance.sh TraceAnalyzer Location: tools/perf/TraceAnalyzer/ Documentation: docs/getting-perf-traces.md

Prerequisites

Windows

PowerShell 7+
dotnet-trace global tool (dotnet tool install -g dotnet-trace)
.NET SDK (restored via ./restore.cmd or ./restore.sh)

macOS / Linux

Bash 4+
dotnet-trace global tool (dotnet tool install -g dotnet-trace)
python3 (for parsing launchSettings.json)
.NET SDK (restored via ./restore.sh)

Quick Start

Single Measurement

# From repository root — measures the default TestShop.AppHost (Windows)
.\tools\perf\Measure-StartupPerformance.ps1

# From repository root — measures the default TestShop.AppHost (macOS/Linux)
./tools/perf/measure-startup-performance.sh

Multiple Iterations with Statistics

.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5

./tools/perf/measure-startup-performance.sh --iterations 5

Custom Project

.\tools\perf\Measure-StartupPerformance.ps1 -ProjectPath "path\to\MyApp.AppHost.csproj" -Iterations 3

./tools/perf/measure-startup-performance.sh --project-path path/to/MyApp.AppHost.csproj --iterations 3

Preserve Traces for Manual Analysis

.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 3 -PreserveTraces -TraceOutputDirectory "C:\traces"

./tools/perf/measure-startup-performance.sh --iterations 3 --preserve-traces --trace-output-directory /tmp/traces

Verbose Output

.\tools\perf\Measure-StartupPerformance.ps1 -Verbose

./tools/perf/measure-startup-performance.sh --verbose

Parameters

PowerShell Parameter	Bash Parameter	Default	Description
`-ProjectPath`	`--project-path`	TestShop.AppHost	Path to the AppHost `.csproj` to measure
`-Iterations`	`--iterations`	1	Number of measurement runs (1–100)
`-PreserveTraces`	`--preserve-traces`	false	Keep `.nettrace` files after analysis
`-TraceOutputDirectory`	`--trace-output-directory`	temp folder	Directory for preserved trace files
`-SkipBuild`	`--skip-build`	false	Skip `dotnet build` before running
`-TraceDurationSeconds`	`--trace-duration-seconds`	60	Maximum trace collection time (1–86400)
`-PauseBetweenIterationsSeconds`	`--pause-between-iterations-seconds`	45	Pause between iterations (0–3600)
`-Verbose`	`--verbose`	false	Show detailed output

How It Works

The script follows this sequence:

Prerequisites check — Verifies dotnet-trace is installed and the project exists.
Build — Builds the AppHost project in Release configuration (unless -SkipBuild).
Build TraceAnalyzer — Builds the companion tools/perf/TraceAnalyzer project.
For each iteration: a. Locates the compiled executable (Arcade-style or traditional output paths). b. Reads launchSettings.json for environment variables. c. Launches the AppHost as a separate process. d. Attaches dotnet-trace to the running process with the Microsoft-Aspire-Hosting provider. e. Waits for the trace to complete (duration timeout or process exit). f. Runs the TraceAnalyzer to extract the startup duration from the .nettrace file. g. Cleans up processes.
Reports results — Prints per-iteration times and statistics (min, max, average, std dev).

TraceAnalyzer Tool

The tools/perf/TraceAnalyzer is a small .NET console app that parses .nettrace files using the Microsoft.Diagnostics.Tracing.TraceEvent library.

What It Does

Opens the .nettrace file with EventPipeEventSource
Listens for events from the Microsoft-Aspire-Hosting provider
Extracts timestamps for DcpModelCreationStart (ID 17) and DcpModelCreationStop (ID 18)
Outputs the duration in milliseconds (or "null" if events are not found)

Standalone Usage

dotnet run --project tools/perf/TraceAnalyzer -c Release -- <path-to-nettrace-file>

Understanding Output

Successful Run

==================================================
 Aspire Startup Performance Measurement
==================================================

Project: TestShop.AppHost
Iterations: 3
...

Iteration 1
----------------------------------------
Starting TestShop.AppHost...
Attaching trace collection to PID 12345...
Collecting performance trace...
Trace collection completed.
Analyzing trace: ...
Startup time: 1234.56 ms

...

==================================================
 Results Summary
==================================================

Iteration StartupTimeMs
--------- -------------
        1       1234.56
        2       1189.23
        3       1201.45

Statistics:
  Successful iterations: 3 / 3
  Minimum: 1189.23 ms
  Maximum: 1234.56 ms
  Average: 1208.41 ms
  Std Dev: 18.92 ms

Common Issues

Symptom	Cause	Fix
`dotnet-trace is not installed`	Missing global tool	Run `dotnet tool install -g dotnet-trace`
`Could not find compiled executable`	Project not built	Remove `-SkipBuild` or build manually
`Could not find DcpModelCreation events`	Trace too short or events not emitted	Increase `-TraceDurationSeconds`
`Application exited immediately`	App crash on startup	Check app logs, ensure dependencies are available
`dotnet-trace exited with code != 0`	Trace collection error	Check verbose output; trace file may still be valid

Comparing Before/After Performance

To measure the impact of a code change:

# Windows: Measure baseline (on main branch)
git checkout main
.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5 -PreserveTraces -TraceOutputDirectory "C:\traces\baseline"

# Windows: Measure with changes
git checkout my-feature-branch
.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5 -PreserveTraces -TraceOutputDirectory "C:\traces\feature"

# Compare the reported averages and std devs

# macOS/Linux: Measure baseline (on main branch)
git checkout main
./tools/perf/measure-startup-performance.sh --iterations 5 --preserve-traces --trace-output-directory /tmp/traces/baseline

# macOS/Linux: Measure with changes
git checkout my-feature-branch
./tools/perf/measure-startup-performance.sh --iterations 5 --preserve-traces --trace-output-directory /tmp/traces/feature

# Compare the reported averages and std devs

Use enough iterations (5+) and a consistent pause between iterations for reliable comparisons.

Collecting Traces for Manual Analysis

If you need to inspect trace files manually (e.g., in PerfView or Visual Studio):

.\tools\perf\Measure-StartupPerformance.ps1 -PreserveTraces -TraceOutputDirectory "C:\my-traces"

./tools/perf/measure-startup-performance.sh --preserve-traces --trace-output-directory /tmp/my-traces

See docs/getting-perf-traces.md for guidance on analyzing traces with PerfView or dotnet trace report.

EventSource Provider Details

The Microsoft-Aspire-Hosting EventSource emits events for key Aspire lifecycle milestones. The startup performance script focuses on:

Event ID	Event Name	Description
17	`DcpModelCreationStart`	Marks the beginning of DCP model creation
18	`DcpModelCreationStop`	Marks the completion of DCP model creation

The measured startup time is the wall-clock difference between these two events, representing the time to create all application services and supporting dependencies.