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/net10.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.

Instrumentation Guidance

Keep profiling APIs coarse-grained and profiling-specific:

• Centralize raw Activity, activity names, tag names, and event names in the profiling telemetry type for the area (Aspire.Cli.Profiling or Aspire.Hosting.Profiling).
• Do not expose one public/internal method per tag. Prefer operation/result-level methods that accept the data for a phase and set multiple tags/events internally.
• Good API shape examples: start a dotnet process span with command, project, working directory, and options; record a process start result with started/process ID; record process completion with exit code and output counts; start a Kubernetes API span with operation/resource type; record retry details as one event method.
• Call sites should describe the operation being profiled, not know tag/event names.
• Do not add profiling tags/events to Activity.Current unless the current activity is known to be a profiling activity or profiling has explicitly wrapped it.
• Keep high-cardinality data out of reported telemetry.

Common Issues