aspire otel spans command

Ce contenu n’est pas encore disponible dans votre langue.

Name

aspire otel spans - View spans from the Dashboard telemetry API.

Synopsis

aspire otel spans [resource] [options]

Description

The aspire otel spans command retrieves and displays distributed trace spans collected by the Aspire Dashboard. Spans represent individual units of work within a distributed trace, such as HTTP requests or database calls. You can filter spans by resource name, trace ID, error status, or a full-text search expression. Use --follow to stream spans in real-time as they arrive.

Arguments

[resource]

Filter by resource name. When specified, only spans from the matching resource are shown. Supports both exact instance names and base resource names (which match all replicas).

Options

The following options are available:

--apphost <apphost>

The path to the Aspire AppHost project file. Mutually exclusive with --dashboard-url.
--dashboard-url <url>

The URL of a standalone Aspire Dashboard to query instead of discovering one from an AppHost. Accepts a base URL (for example, http://localhost:18888) or a full login URL including a browser token (for example, http://localhost:18888/login?t=<token>). When a login URL is provided, the token is automatically exchanged for an API key. Mutually exclusive with --apphost.
--api-key <key>

The API key used to authenticate with the dashboard’s Telemetry API. Only required when --dashboard-url is specified and the dashboard is configured with ApiKey authentication and no login URL is provided.
-f, --follow

Stream telemetry in real-time as it arrives.
--format <Table|Json>

Output format (Table or Json).
-n, --limit <limit>

Maximum number of items to return.
--trace-id <trace-id>

Filter by trace ID.
--has-error <true|false>

Filter by error status (true to show only errors, false to exclude errors).

--search <search>

Full-text search across span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured field:value qualifiers. For more information, see Search and filter.

Syntax	Meaning
`word`	Free-text fragment — matches any searchable field
`"quoted phrase"`	Single fragment containing spaces
`field:value`	Field qualifier — value must match the named field
`-field:value`	Negated qualifier — excludes matches
`field:>N` / `field:>=N` / `field:<N` / `field:<=N`	Comparison for numeric fields
`@attr:value`	Attribute qualifier — matches custom span attributes

Supported fields for spans: resource, name, span-id, trace-id, status, kind, duration.

-?, -h, --help

Prints help and usage documentation for the available commands and options.
-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.
--non-interactive

Run the command in non-interactive mode, disabling all interactive prompts and spinners.
--nologo

Suppress the startup banner and telemetry notice.
--banner

Display the animated Aspire CLI welcome banner.
--wait-for-debugger

Wait for a debugger to attach before running a command.

Examples

View all spans:
Aspire CLI
```
aspire otel spans
```
View spans for a specific resource:
Aspire CLI
```
aspire otel spans apiservice
```
Stream spans in real-time:
Aspire CLI
```
aspire otel spans --follow
```
View only error spans:
Aspire CLI
```
aspire otel spans --has-error true
```
View spans for a specific trace in JSON format:
Aspire CLI
```
aspire otel spans --trace-id abc123 --format Json
```

Search spans by text:

aspire otel spans --search "/api/orders"

Filter spans by attribute value:

aspire otel spans --search "@db.system:postgresql"

View spans from a standalone dashboard using the login URL (token is automatically exchanged for an API key):
Aspire CLI
```
aspire otel spans --dashboard-url "http://localhost:18888/login?t=<token>"
```

View spans from a secured standalone Aspire Dashboard:

aspire otel spans --dashboard-url "http://localhost:18888" --api-key "<your-api-key>"