diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index 7f8024471..fd11eafbd 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -213,6 +213,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { }, slug: 'reference/cli/install-script', }, + { + label: 'Search and filter', + slug: 'reference/cli/search-filter', + }, { label: 'Configuration', translations: { diff --git a/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx b/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx index 57862efee..2042e12e9 100644 --- a/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx @@ -1,5 +1,5 @@ --- -title: Dashboard and AI coding agents +title: AI coding agents and the Aspire Dashboard seoTitle: Aspire dashboard and AI coding agents for distributed apps description: Learn how AI coding agents use the Aspire CLI and MCP server to read logs and telemetry from the Aspire dashboard, diagnose failures, and propose code changes. --- diff --git a/src/frontend/src/content/docs/fundamentals/telemetry.mdx b/src/frontend/src/content/docs/fundamentals/telemetry.mdx index b22c31746..36cbe9e9c 100644 --- a/src/frontend/src/content/docs/fundamentals/telemetry.mdx +++ b/src/frontend/src/content/docs/fundamentals/telemetry.mdx @@ -73,6 +73,34 @@ When you start an Aspire project with debugging (pressing F5), the fo All of these steps happen internally, so in most cases you simply need to run the app to see this process in action. +### Use telemetry with AI coding agents + +AI coding agents can access Aspire telemetry to diagnose issues, inspect app behavior, and monitor resources without requiring you to manually copy data from the dashboard. The Aspire CLI is built for agent-driven workflows—commands support non-interactive execution and `--format Json` for structured output that agents can parse. + +When running an Aspire AppHost, agents use CLI commands like `aspire otel logs`, `aspire otel traces`, and `aspire describe` to fetch structured logs, distributed traces, and resource status directly from the dashboard. A typical agent workflow starts the app with `aspire start`, waits for resources with `aspire wait`, then queries telemetry to diagnose issues and verify fixes. + +When using a standalone dashboard, agents pass `--dashboard-url` to point CLI commands at the dashboard instance and query telemetry from any application sending OTLP data. + + + +- [AI coding agents and Aspire](/get-started/ai-coding-agents/) — using AI agents with an Aspire AppHost +- [AI coding agents and the Aspire Dashboard](/dashboard/ai-coding-agents/#standalone-mode) — using AI agents with a standalone dashboard + + + +## APIs and data access + +The Aspire dashboard exposes APIs for both receiving and querying telemetry data. Applications write data to the dashboard using OTLP endpoints, and developers and tools read data back through multiple interfaces: + +- **Aspire CLI** — The `aspire otel logs`, `aspire otel traces`, and `aspire otel spans` commands query telemetry directly from the terminal. Use `--format Json` for structured output suitable for scripting and automation. +- **Export** — The `aspire export` command packages telemetry and resource data into a zip file for offline analysis or sharing. +- **MCP server** — The Aspire MCP server exposes dashboard data to AI coding agents through Model Context Protocol tools. +- **HTTP telemetry API** — The dashboard exposes HTTP endpoints under `/api/telemetry/` that return data in OTLP JSON format, supporting real-time streaming and resource filtering. + + +For more information, see [Dashboard APIs and data access](/dashboard/apis/). + + ## Deployment Aspire deployment environments should configure OpenTelemetry environment variables that make sense for their environment. For example, `OTEL_EXPORTER_OTLP_ENDPOINT` should be configured to the environment's local OTLP collector or monitoring service. diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-logs.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-logs.mdx index 37d9c9d51..f93b77015 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-logs.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-logs.mdx @@ -58,7 +58,7 @@ The following options are available: - **`-s, --search `** - Full-text search to filter log content. Only log lines whose message or resource name contains the specified text are shown. Multiple words are treated as separate fragments that must all match. Use quoted phrases to match exact multi-word text (for example, `--search '"connection timeout"'`). + Full-text search to filter log content. Only log lines whose message or resource name contains the specified text are shown. Multiple words are treated as separate fragments that must all match. Use quoted phrases to match exact multi-word text (for example, `--search '"connection timeout"'`). For more information, see [Search and filter](/reference/cli/search-filter/). - **`-t, --timestamps`** diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx index 4612e4431..2db579e2a 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx @@ -75,7 +75,7 @@ The following options are available: - **`--search `** - Full-text search across log text fields, such as log messages, attribute values, scope, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. + Full-text search across log text fields, such as log messages, attribute values, scope, 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 | |--------|---------| diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx index b1e3fd2fc..38b5326a8 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx @@ -75,7 +75,7 @@ The following options are available: - **`--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. + 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 | |--------|---------| diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx index 4620f3dd9..e225a6a8e 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx @@ -73,7 +73,7 @@ The following options are available: - **`--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. + 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 | |--------|---------| diff --git a/src/frontend/src/content/docs/reference/cli/overview.mdx b/src/frontend/src/content/docs/reference/cli/overview.mdx index 785944bcf..28c098815 100644 --- a/src/frontend/src/content/docs/reference/cli/overview.mdx +++ b/src/frontend/src/content/docs/reference/cli/overview.mdx @@ -214,6 +214,12 @@ Use `aspire describe`, `aspire logs`, and `aspire export` to inspect resources, [Command reference: `aspire describe`](../commands/aspire-describe/), [Command reference: `aspire logs`](../commands/aspire-logs/), [Command reference: `aspire export`](../commands/aspire-export/), and [Command reference: `aspire otel`](../commands/aspire-otel/) +Use the `--search` option with `aspire logs` and `aspire otel` commands to filter output by matching text against log content and trace/span fields. Search supports free-text fragments, structured `field:value` qualifiers, negation, and comparison operators. + + + [Search and filter](../search-filter/) + + ## Diagnose and prepare the environment Use `aspire doctor` to verify that your environment is ready for Aspire development, and `aspire certs` to manage the HTTPS development certificates used by local resources and dashboards. diff --git a/src/frontend/src/content/docs/reference/cli/search-filter.mdx b/src/frontend/src/content/docs/reference/cli/search-filter.mdx new file mode 100644 index 000000000..31cb7e874 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/search-filter.mdx @@ -0,0 +1,85 @@ +--- +title: Search and filter +description: Learn how to use the --search option to filter logs, traces, and spans in the Aspire CLI. +--- + +The `--search` option filters output by matching against text and attributes on returned data. Search is supported by these commands: + +- [`aspire logs`](../commands/aspire-logs/) +- [`aspire otel logs`](../commands/aspire-otel-logs/) +- [`aspire otel spans`](../commands/aspire-otel-spans/) +- [`aspire otel traces`](../commands/aspire-otel-traces/) + +For example, to filter console logs for a specific resource by text: + +```bash title="Aspire CLI" +aspire logs redis --search "timeout" +``` + +## Search syntax + +Search queries support free-text fragments, field qualifiers, attribute qualifiers, negation, and comparison operators. + +| Syntax | Meaning | Example | +|--------|---------|---------| +| `word` | Free-text fragment — must appear in at least one searchable field | `timeout` | +| `"quoted phrase"` | Single fragment containing spaces | `"connection refused"` | +| `field:value` | Field qualifier — value must match the named field | `severity:error` | +| `field:"value with spaces"` | Quoted field qualifier value | `message:"connection failed"` | +| `@attr:value` | Attribute qualifier — matches custom span/log attributes | `@http.method:GET` | +| `-field:value` / `-@attr:value` | Negated qualifier — excludes matches | `-severity:debug` | +| `field:>N` / `field:>=N` / `field:100` | + +All terms are AND'd: every fragment and qualifier must independently match. + +## Console logs + +Matches against log line text content and resource name. Only free-text is supported (no structured qualifiers). + +```bash title="Aspire CLI" +aspire logs redis --search "timeout" +aspire logs --follow --search "\"connection error\"" +``` + +## Structured logs + +Supports free-text and structured qualifiers. Free-text matches against message, resource name, scope, trace/span IDs, severity, and all attribute keys/values. + +Available field qualifiers: `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event`. + +```bash title="Aspire CLI" +aspire otel logs --search "severity:error \"connection failed\"" +aspire otel logs --search "resource:api -severity:debug" +aspire otel logs --search "scope:Microsoft.EntityFrameworkCore" +``` + +## Traces + +Supports free-text and structured qualifiers. Free-text matches against trace name, resource name, and all span fields within the trace. + +Available field qualifiers: `name`, `resource`, `trace-id`, `status`, `duration`. + +```bash title="Aspire CLI" +aspire otel traces --search "checkout" +aspire otel traces --search "status:error duration:>500" +aspire otel traces --search "@http.status_code:500" +``` + +## Spans + +Supports free-text and structured qualifiers. Free-text matches against span name, resource name, scope, trace/span IDs, status, kind, and all attribute keys/values. + +Available field qualifiers: `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration`. + +```bash title="Aspire CLI" +aspire otel spans --search "@http.method:GET duration:>100 status:error" +aspire otel spans --search "@db.system:postgresql" +aspire otel spans --search "-kind:internal" +``` + +## See also + +- [Command reference: `aspire logs`](../commands/aspire-logs/) +- [Command reference: `aspire otel logs`](../commands/aspire-otel-logs/) +- [Command reference: `aspire otel spans`](../commands/aspire-otel-spans/) +- [Command reference: `aspire otel traces`](../commands/aspire-otel-traces/)