Startup Perf

Aspire Startup Profiling with OTEL

Use this skill when measuring, validating, or investigating Aspire startup performance with the CLI self-profile capture flow.

The workflow is the hidden CLI flag --capture-profile. It starts a private standalone dashboard collector, enables profiling-only OTEL instrumentation for the command and child AppHost processes, exports a trace archive, and then exits with the wrapped command's exit code.

Current Profiling Model

Profiling is opt-in and separate from reported telemetry:

• Enable profiling with ASPIRE_PROFILING_ENABLED=true or 1.
• CLI profiling spans use the Aspire.Cli.Profiling ActivitySource.
• Hosting profiling spans use the Aspire.Hosting.Profiling ActivitySource.
• DCP startup spans use the dcp.startup instrumentation scope when DCP emits startup telemetry.
• Reported telemetry must not carry profiling session IDs, high-cardinality profiling tags, or profiling spans.

Prerequisites

Use an Aspire CLI build that contains --capture-profile. From a repo checkout:

./restore.sh
./dotnet.sh build src/Aspire.Cli/Aspire.Cli.csproj /p:SkipNativeBuild=true

Repo-local development builds discover the built managed dashboard from artifacts/bin/Aspire.Managed when ASPIRE_REPO_ROOT points at the checkout. Installed or bundled CLIs discover the dashboard from the bundle. Use ASPIRE_DASHBOARD_PATH / ASPIRE_MANAGED_PATH when profiling with a custom dashboard build.

Quick Start

Capture startup for an AppHost and exit automatically after startup:

./dotnet.sh exec artifacts/bin/Aspire.Cli/Debug/net11.0/aspire.dll run \
  --project tests/TestingAppHost1/TestingAppHost1.AppHost/TestingAppHost1.AppHost.csproj \
  --capture-profile \
  --capture-profile-output artifacts/tmp/startup-profile/profile.zip \
  --non-interactive

Capture any other Aspire command:

aspire ls \
  --capture-profile \
  --capture-profile-output artifacts/tmp/startup-profile/ls-profile.zip \
  --non-interactive

If --capture-profile-output is omitted, the CLI writes aspire-profile-<timestamp>-<session>.zip under the current working directory. For long-lived run and start, the CLI exits automatically after startup and waits for profiling data to settle before writing the export.

Self-Profile Options

Output Artifacts

The capture writes a dashboard export zip containing:

Inspect the export:

unzip -l artifacts/tmp/startup-profile/profile.zip
tmpdir="$(mktemp -d)"
unzip -q artifacts/tmp/startup-profile/profile.zip -d "$tmpdir"
jq -r '.resourceSpans[]?.scopeSpans[]?.scope.name' "$tmpdir/traces/profile.json" | sort | uniq -c
jq -r '.resourceSpans[]?.scopeSpans[]?.spans[]?.name' "$tmpdir/traces/profile.json" | sort | uniq -c

Expected startup captures include:

• Aspire.Cli.Profiling spans such as aspire/cli/command, aspire/cli/run, dotnet process spans, backchannel connect spans, and dashboard URL retrieval.
• Aspire.Hosting.Profiling spans such as DCP model work, resource creation, resource wait, and DCP resource observation.
• dcp.startup spans when the DCP process emits startup telemetry and the scenario is configured to require them.

Comparing Before/After Changes

Prefer separate worktrees for baseline and feature measurements so branch switching does not disturb a dirty worktree.

# Baseline worktree
aspire run --project path/to/AppHost.csproj \
  --capture-profile \
  --capture-profile-output artifacts/tmp/startup-profile-baseline/profile.zip \
  --non-interactive

# Feature worktree
aspire run --project path/to/AppHost.csproj \
  --capture-profile \
  --capture-profile-output artifacts/tmp/startup-profile-feature/profile.zip \
  --non-interactive

Compare traces/profile.json span names, durations, operation IDs, process IDs, events, and trace correlation. For statistically meaningful wall-clock comparisons, run multiple iterations manually and keep the environment stable. The self-profile capture flow produces artifacts; it is not a statistical benchmark runner by itself.

Parallel captures are supported because each --capture-profile process allocates its own collector ports and profiling session ID. Always use distinct --capture-profile-output paths. If the profiled AppHost launch profile pins dashboard, resource-service, or application ports, those AppHost ports can still conflict across parallel worktrees; use an isolated/randomized profile or adjust the AppHost ports for parallel runs.