Labsco
microsoft logo

startup-perf

✓ Official★ 6,100

by microsoft · part of microsoft/aspire

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…

🔥🔥✓ VerifiedFreeQuick setup
#git
🔒 Repo-maintenance skill. It exists to help maintain microsoft/aspire itself — it's only useful if you contribute code to that project.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

name: startup-perf description: Measures Aspire startup profiling with CLI self-profile capture and dashboard export traces.

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.

Self-Profile Options

OptionDescription
--capture-profileHidden recursive root option that enables self-profile capture for any Aspire command.
--capture-profile-output PATHOutput zip path. Relative paths are rooted at the current working directory.
--capture-profile-delay SECONDSOptional warmup delay before stopping long-lived run/start commands. Defaults to 5 seconds so AppHost-side spans have time to flush before shutdown. Increase it when you intentionally want additional post-start resource activity in the capture.

Output Artifacts

The capture writes a dashboard export zip containing:

PathDescription
traces/profile.jsonOTLP JSON trace export from the private dashboard collector.

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.