Skip to content

[docs] Add profiling spans and options for aspire add command #1037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.4
Choose a base branch
from
+45 −0
Open

[docs] Add profiling spans and options for aspire add command #1037

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,45 @@ The following options are available:

- <Include relativePath="reference/cli/includes/option-wait.md" />

- **`--capture-profile`**

Capture an OpenTelemetry trace of the `aspire add` command execution and save it as a self-contained ZIP file. Use this to identify which phase of the add flow — package search, package selection, or package installation — is taking the most time.

- **`--capture-profile-output <path>`**

The output path for the captured profile ZIP file. Defaults to a timestamped file in the current directory when `--capture-profile` is used.

## Profiling spans

When `--capture-profile` is enabled, `aspire add` emits the following OpenTelemetry spans:

| Span | Description |
|------|-------------|
| `aspire/cli/add` | Root span for the entire add command. Marked with error status and exit code on all graceful failure paths. |
| `aspire/cli/add.find_apphost` | AppHost project discovery. |
| `aspire/cli/add.get_configured_channel` | NuGet channel lookup via MSBuild. |
| `aspire/cli/add.search_packages` | `dotnet package search` call for Aspire integrations. |
| `aspire/cli/add.select_package` | Records match count, match kind, and the selected package. Does not include user think time. |
| `aspire/cli/add.select_package.prompt` | Wraps the interactive package and version prompts so that user think time is distinguishable from tool time. |
| `aspire/cli/add.stop_existing_instance` | Stopping any running AppHost before installation. |
| `aspire/cli/add.package` | `dotnet package add` installation step. |

Each span may carry the following tags:

| Tag | Description |
|-----|-------------|
| `aspire.cli.add.integration.name` | The integration name passed to `aspire add`. |
| `version_specified` | Whether a specific version was requested. |
| `source_specified` | Whether a custom NuGet source was specified. |
| `configured_channel` | The NuGet channel resolved via MSBuild. |
| `package.search_result_count` | Total number of packages returned by `dotnet package search`. |
| `package.match_count` | Number of packages that matched the search term. |
| `package.match_kind` | How the package was matched: `exact`, `fuzzy`, or `none`. |
| `package.id` | The NuGet package ID of the selected package. |
| `package.version` | The version of the selected package. |
| `package.channel` | The NuGet channel the package was resolved from. |
| `package.success` | Whether the package installation succeeded. |

## Examples

- Finds an AppHost project and lists all Aspire integration packages from NuGet:
Expand All @@ -75,3 +114,9 @@ The following options are available:
```bash title="Aspire CLI"
aspire add kafka --version 13.3.0
```

- Adds the **redis** integration and captures a profiling trace to a ZIP file:

```bash title="Aspire CLI"
aspire add redis --version 9.5.0 --capture-profile --capture-profile-output add-redis.zip
```
Loading