# aspire otel spans command

## Name

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

## Synopsis

```bash title="Aspire CLI"
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](/reference/cli/search-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`.

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

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

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

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

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

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

## Examples

- View all spans:

  ```bash title="Aspire CLI"
  aspire otel spans
  ```

- View spans for a specific resource:

  ```bash title="Aspire CLI"
  aspire otel spans apiservice
  ```

- Stream spans in real-time:

  ```bash title="Aspire CLI"
  aspire otel spans --follow
  ```

- View only error spans:

  ```bash title="Aspire CLI"
  aspire otel spans --has-error true
  ```

- View spans for a specific trace in JSON format:

  ```bash title="Aspire CLI"
  aspire otel spans --trace-id abc123 --format Json
  ```

- Search spans by text:

  ```bash title="Aspire CLI"
  aspire otel spans --search "/api/orders"
  ```

- Filter spans by attribute value:

  ```bash title="Aspire CLI"
  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):

  ```bash title="Aspire CLI"
  aspire otel spans --dashboard-url "http://localhost:18888/login?t=<token>"
  ```

- View spans from a secured standalone Aspire Dashboard:

  ```bash title="Aspire CLI"
  aspire otel spans --dashboard-url "http://localhost:18888" --api-key "<your-api-key>"
  ```

## See also

- [aspire otel command](../aspire-otel/)
- [aspire otel logs command](../aspire-otel-logs/)
- [aspire otel traces command](../aspire-otel-traces/)