From 8643486390ad71208a15954bbcdfd9592d5b093a Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 03:38:30 +0000 Subject: [PATCH] Update dashboard API defaults and otel command docs - Dashboard:Api:Enabled now defaults to true (API enabled by default) - Dashboard:Api:AuthMode now defaults to ApiKey - Add Dashboard:Api:Disabled as the new preferred config to disable the API - Mark Dashboard:Api:Enabled as deprecated in docs - Update PrimaryApiKey default to note auto-generation - Add --dashboard-url and --api-key options to aspire otel logs/spans/traces - Document login URL support: passing http://host/login?t= auto-exchanges the token for an API key - Update aspire otel main page description to mention standalone dashboard usage Documents changes from microsoft/aspire#16326 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../config/sidebar/reference.topics.ts | 14 ++++ .../content/docs/dashboard/configuration.mdx | 9 +- .../src/content/docs/dashboard/standalone.mdx | 46 ++++++++++ .../cli/commands/aspire-agent-mcp.mdx | 22 +++++ .../cli/commands/aspire-dashboard-run.mdx | 84 +++++++++++++++++++ .../cli/commands/aspire-dashboard.mdx | 43 ++++++++++ .../cli/commands/aspire-otel-logs.mdx | 14 ++++ .../cli/commands/aspire-otel-spans.mdx | 14 ++++ .../cli/commands/aspire-otel-traces.mdx | 14 ++++ .../reference/cli/commands/aspire-otel.mdx | 2 +- 10 files changed, 257 insertions(+), 5 deletions(-) create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard.mdx diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index 56a069e54..055e924ce 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -467,6 +467,20 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { }, ], }, + { + label: 'aspire dashboard', + collapsed: true, + items: [ + { + label: 'aspire dashboard', + slug: 'reference/cli/commands/aspire-dashboard', + }, + { + label: 'aspire dashboard run', + slug: 'reference/cli/commands/aspire-dashboard-run', + }, + ], + }, { label: 'aspire deploy', slug: 'reference/cli/commands/aspire-deploy', diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx index 53d54b8cb..eca20ac08 100644 --- a/src/frontend/src/content/docs/dashboard/configuration.mdx +++ b/src/frontend/src/content/docs/dashboard/configuration.mdx @@ -203,13 +203,14 @@ API key authentication works by requiring each MCP request to have a valid `x-mc ## API -The API section configures authentication for the dashboard's HTTP API endpoints. +The API section configures the dashboard's Telemetry HTTP API (`/api/telemetry/*`) endpoints. The API is enabled by default and secured with API key authentication. The API key is auto-generated if one isn't provided. | Option | Description | |--------|-------------| -| `Dashboard:Api:Enabled`
Default: `false` | Enables the Telemetry HTTP API (`/api/telemetry/*`) endpoints. When `false`, the endpoints are not registered. | -| `Dashboard:Api:AuthMode`
Default: `Unsecured` | Can be set to `ApiKey` or `Unsecured`. `Unsecured` should only be used during local development. If an API key is configured and no auth mode is specified, defaults to `ApiKey`. | -| `Dashboard:Api:PrimaryApiKey`
Default: `null` | Specifies the primary API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended. This value is required if auth mode is API key. | +| `Dashboard:Api:Disabled`
Default: `false` | Disables the Telemetry HTTP API (`/api/telemetry/*`) endpoints. When `true`, the endpoints are not registered. Set `ASPIRE_DASHBOARD_API_DISABLED=true` to disable the API via environment variable. | +| `Dashboard:Api:Enabled`
Default: `true` | **Deprecated.** Use `Dashboard:Api:Disabled` instead. When `false`, disables the Telemetry HTTP API endpoints. | +| `Dashboard:Api:AuthMode`
Default: `ApiKey` | Can be set to `ApiKey` or `Unsecured`. `Unsecured` should only be used during local development. | +| `Dashboard:Api:PrimaryApiKey`
Default: Auto-generated | Specifies the primary API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended. When auth mode is `ApiKey` and no key is provided, a 128-bit key is auto-generated at startup. | | `Dashboard:Api:SecondaryApiKey`
Default: `null` | Specifies the secondary API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended. This value is optional. | ## Resources diff --git a/src/frontend/src/content/docs/dashboard/standalone.mdx b/src/frontend/src/content/docs/dashboard/standalone.mdx index 4d0308a3e..685ddddef 100644 --- a/src/frontend/src/content/docs/dashboard/standalone.mdx +++ b/src/frontend/src/content/docs/dashboard/standalone.mdx @@ -23,6 +23,8 @@ The [Aspire dashboard](/dashboard/overview/) provides a great UI for viewing tel ## Start the dashboard +### Docker + The dashboard is started using the Docker command line. @@ -60,6 +62,24 @@ The preceding Docker command: - Mapping the dashboard's OTLP/gRPC port `18889` to the host's port `4317`. Port `4317` receives OpenTelemetry data from apps using [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). - Mapping the dashboard's OTLP/HTTP port `18890` to the host's port `4318`. Port `4318` receives OpenTelemetry data from apps using [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp). +### Aspire CLI + +If you have the [Aspire CLI](/reference/cli/) installed, you can start the dashboard with a single command: + +```bash title="Aspire CLI" +aspire dashboard run +``` + +The dashboard starts with the following defaults: + +- **Frontend UI** at `http://localhost:18888` +- **OTLP/gRPC** endpoint at `http://localhost:4317` +- **OTLP/HTTP** endpoint at `http://localhost:4318` + +The dashboard is secured with a browser token by default. A login URL with the token is displayed in the terminal output. Use `--allow-anonymous` to disable authentication during local development. + +For all available options, see the [`aspire dashboard run`](/reference/cli/commands/aspire-dashboard-run/) command reference. + ## Login to the dashboard Data displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login. @@ -153,6 +173,32 @@ To configure applications: Additional configuration may be required to authenticate with the dashboard if you have configured the dashboard to secure the telemetry endpoint. For more information, see [Securing the telemetry endpoint](/dashboard/security-considerations/#secure-telemetry-endpoint). +## Query telemetry with the Aspire CLI + +The [Aspire CLI](/reference/cli/) can query telemetry data directly from the dashboard's API, allowing you to view logs, traces, and spans from the terminal without opening the dashboard UI. + +The dashboard's telemetry API is secured with API key authentication by default. When using the CLI commands, you can pass the dashboard's login URL (including the browser token) via `--dashboard-url` and the token is automatically exchanged for an API key. Alternatively, if the dashboard is started with `aspire dashboard run --allow-anonymous` or the `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` environment variable is set to `true`, no authentication is required — this should only be used during local development. + +### View telemetry with `aspire otel` + +The [`aspire otel`](/reference/cli/commands/aspire-otel/) commands retrieve telemetry from the dashboard. Use `--dashboard-url` to point at a standalone dashboard — you can paste the full login URL and the browser token is automatically exchanged for an API key: + +```bash title="Aspire CLI" +aspire otel logs --dashboard-url "http://localhost:18888/login?t=" +aspire otel traces --dashboard-url "http://localhost:18888/login?t=" +aspire otel spans --dashboard-url "http://localhost:18888/login?t=" +``` + +For more details, see the [`aspire otel logs`](/reference/cli/commands/aspire-otel-logs/), [`aspire otel traces`](/reference/cli/commands/aspire-otel-traces/), and [`aspire otel spans`](/reference/cli/commands/aspire-otel-spans/) command references. + +### Use AI agents with `aspire agent mcp` + +The [`aspire agent mcp`](/reference/cli/commands/aspire-agent-mcp/) command starts an MCP (Model Context Protocol) server that AI assistants can connect to. When used with `--dashboard-url`, it runs in dashboard-only mode and exposes telemetry tools (structured logs and traces) to MCP-compatible clients: + +```bash title="Aspire CLI" +aspire agent mcp --dashboard-url "http://localhost:18888/login?t=" +``` + ## Sample For a sample of using the standalone dashboard, see the [Standalone Aspire dashboard sample app](https://github.com/dotnet/aspire-samples/tree/main/samples/standalone-dashboard). diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-mcp.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-mcp.mdx index caba58836..4106ba37e 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-mcp.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-agent-mcp.mdx @@ -36,10 +36,20 @@ When the server is running, MCP-compatible clients can connect to it to: - Execute resource commands (start, stop, restart) - Query integration information +You can also run the MCP server in dashboard-only mode by providing `--dashboard-url`. In this mode, only telemetry tools (structured logs, traces) are available — resource management tools that require an AppHost are not registered. + ## Options The following options are available: +- **`--dashboard-url `** + + The URL of a standalone Aspire Dashboard to connect to 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=`). When a login URL is provided, the token is automatically exchanged for an API key. When this option is specified, the server runs in dashboard-only mode with only telemetry tools available. + +- **`--api-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. + - - @@ -60,6 +70,18 @@ The following options are available: aspire agent mcp ``` +- Start the MCP server in dashboard-only mode using a login URL: + + ```bash title="Aspire CLI" + aspire agent mcp --dashboard-url "http://localhost:18888/login?t=" + ``` + +- Start the MCP server in dashboard-only mode with an API key: + + ```bash title="Aspire CLI" + aspire agent mcp --dashboard-url "http://localhost:18888" --api-key "" + ``` + ## See also - [aspire agent command](../aspire-agent/) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx new file mode 100644 index 000000000..3f79ee5a7 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx @@ -0,0 +1,84 @@ +--- +title: aspire dashboard run command +description: Learn about the aspire dashboard run command and its usage. This command starts a standalone Aspire Dashboard instance. +--- + +import Include from '@components/Include.astro'; + +## Name + +`aspire dashboard run` - Start the Aspire dashboard. + +## Synopsis + +```bash title="Aspire CLI" +aspire dashboard run [options] +``` + +## Description + +The `aspire dashboard run` command starts a standalone Aspire Dashboard instance. The dashboard receives OpenTelemetry data (logs, traces, and metrics) and provides a web-based UI for viewing telemetry. + +By default, the dashboard frontend is served at `http://localhost:18888`, the OTLP/gRPC endpoint listens on `http://localhost:4317`, and the OTLP/HTTP endpoint listens on `http://localhost:4318`. All endpoints can be customized using the options below. + +The dashboard is secured with a browser token by default. When the dashboard starts, a login URL with the token is displayed in the terminal. Use `--allow-anonymous` to disable authentication during local development. For more details, see [Dashboard security considerations](/dashboard/security-considerations/). + +Any additional arguments not recognized by the CLI are forwarded directly to the dashboard process, allowing you to pass dashboard configuration settings (for example, `--Dashboard:TelemetryLimits:MaxLogCount=5000`). + +## Options + +The following options are available: + +- **`--frontend-url `** + One or more HTTP endpoints through which the dashboard frontend is served. Default: `http://localhost:18888`. + +- **`--otlp-grpc-url `** + The OTLP/gRPC endpoint. This endpoint hosts an OTLP service and receives telemetry using gRPC. Default: `http://localhost:4317`. + +- **`--otlp-http-url `** + The OTLP/HTTP endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. Default: `http://localhost:4318`. + +- **`--allow-anonymous`** + Allow anonymous access to the dashboard. When not specified, the dashboard is secured with a browser token for the frontend and an API key for the telemetry API. + +- **`--config-file-path `** + The path for a JSON configuration file. + +- +- +- +- +- +- + +## Examples + +- Start the dashboard with default settings: + ```bash title="Aspire CLI" + aspire dashboard run + ``` + +- Start the dashboard on a custom port: + ```bash title="Aspire CLI" + aspire dashboard run --frontend-url http://localhost:9000 + ``` + +- Start with custom OTLP endpoints: + ```bash title="Aspire CLI" + aspire dashboard run --otlp-grpc-url http://localhost:14317 --otlp-http-url http://localhost:14318 + ``` + +- Start with anonymous access (local development only): + ```bash title="Aspire CLI" + aspire dashboard run --allow-anonymous + ``` + +- Start with a JSON configuration file: + ```bash title="Aspire CLI" + aspire dashboard run --config-file-path ./dashboard-config.json + ``` + +## See also + +- [aspire dashboard command](../aspire-dashboard/) +- [Dashboard configuration](../../../dashboard/configuration/) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard.mdx new file mode 100644 index 000000000..122cd1403 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard.mdx @@ -0,0 +1,43 @@ +--- +title: aspire dashboard command +description: Learn about the aspire dashboard command and its usage. This command is used to manage the Aspire dashboard. +--- + +import Include from '@components/Include.astro'; + +## Name + +`aspire dashboard` - Manage the Aspire dashboard. + +## Synopsis + +```bash title="Aspire CLI" +aspire dashboard [command] [options] +``` + +## Description + +The `aspire dashboard` command provides subcommands for managing the Aspire Dashboard. Use it to start a standalone dashboard instance that receives OpenTelemetry data (logs, traces, and metrics) from your applications. + +## Options + +The following options are available: + +- +- +- +- +- +- + +## Commands + +The following commands are available: + +| Command | Function | +| -------------------------------------------------------- | ------------------------------ | +| [`aspire dashboard run`](../aspire-dashboard-run/) | Start the Aspire dashboard. | + +## See also + +- [aspire dashboard run command](../aspire-dashboard-run/) 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 3598ac18d..361f5f952 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 @@ -45,6 +45,14 @@ The following options are available: The path to the Aspire AppHost project file. +- **`--dashboard-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=`). When a login URL is provided, the token is automatically exchanged for an API key. + +- **`--api-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. @@ -109,6 +117,12 @@ The following options are available: aspire otel logs apiservice --limit 50 ``` +- View logs from a standalone dashboard using the login URL (token is automatically exchanged for an API key): + + ```bash title="Aspire CLI" + aspire otel logs --dashboard-url "http://localhost:18888/login?t=" + ``` + ## See also - [aspire otel command](../aspire-otel/) 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 9dad90935..9c1b92fe0 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 @@ -45,6 +45,14 @@ The following options are available: The path to the Aspire AppHost project file. +- **`--dashboard-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=`). When a login URL is provided, the token is automatically exchanged for an API key. + +- **`--api-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. @@ -109,6 +117,12 @@ The following options are available: aspire otel spans --trace-id abc123 --format Json ``` +- 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=" + ``` + ## See also - [aspire otel command](../aspire-otel/) 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 aa293f237..c41f27ac1 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 @@ -47,6 +47,14 @@ The following options are available: The path to the Aspire AppHost project file. +- **`--dashboard-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=`). When a login URL is provided, the token is automatically exchanged for an API key. + +- **`--api-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 `** Output format (Table or Json). @@ -107,6 +115,12 @@ The following options are available: aspire otel traces --limit 20 --format Json ``` +- 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=" + ``` + ## See also - [aspire otel command](../aspire-otel/) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel.mdx index 547f8f871..5bd3f6629 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-otel.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-otel.mdx @@ -25,7 +25,7 @@ aspire otel [command] [options] The `aspire otel` command provides subcommands for viewing OpenTelemetry data collected by the Aspire Dashboard from a running AppHost. You can view structured logs, distributed trace spans, and trace summaries directly from the terminal. -The data is retrieved from the Dashboard's telemetry API, so an AppHost must be running with the Dashboard enabled. +The data is retrieved from the Dashboard's telemetry API. By default, the subcommands discover a running AppHost and connect automatically. You can also use `--dashboard-url` to connect to a standalone dashboard directly — paste the full login URL (for example, `http://localhost:18888/login?t=`) and the browser token is automatically exchanged for an API key. ## Options