# aspire otel traces command

## Name

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

## Synopsis

```bash title="Aspire CLI"
aspire otel traces [resource] [options]
```

## Description

The `aspire otel traces` command retrieves and displays distributed traces collected by the Aspire Dashboard. A trace represents a complete request as it flows through your distributed application. The command shows trace summaries including timestamp, name, span count, duration, and status.

You can view a summary of all traces, or provide a specific trace ID with `--trace-id` to view a detailed span tree for that trace. Use `--search` to filter traces by a full-text search expression.

## Arguments

- **`[resource]`**

  Filter by resource name. When specified, only traces involving 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.

- **`--format <Table|Json>`**

  Output format (Table or Json).

- **`-n, --limit <limit>`**

  Maximum number of items to return.

- **`-t, --trace-id <trace-id>`**

  Filter by trace ID. When specified, displays a detailed span tree for the given trace instead of a summary list.

- **`--has-error <true|false>`**

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

- **`--search <search>`**

  Full-text search across trace and 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 traces: `resource`, `name`, `trace-id`, `status`, `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 traces:

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

- View traces for a specific resource:

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

- View a specific trace detail:

  ```bash title="Aspire CLI"
  aspire otel traces --trace-id abc123
  ```

- View only traces with errors:

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

- View the last 20 traces in JSON format:

  ```bash title="Aspire CLI"
  aspire otel traces --limit 20 --format Json
  ```

- Search traces by text:

  ```bash title="Aspire CLI"
  aspire otel traces --search "checkout"
  ```

- Filter traces by attribute on any constituent span:

  ```bash title="Aspire CLI"
  aspire otel traces --search "@http.status_code:500"
  ```

- View traces from a standalone dashboard using the login URL (token is automatically exchanged for an API key):

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

- View traces from a secured standalone Aspire Dashboard:

  ```bash title="Aspire CLI"
  aspire otel traces --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 spans command](../aspire-otel-spans/)