Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/frontend/src/content/docs/dashboard/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Consider the following example, which shows how to configure the dashboard when
<div slot="unix">

```bash
docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard \
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard \
-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' \
-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' \
-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' \
Expand All @@ -75,7 +75,7 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard \
<div slot="windows">

```powershell
docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard `
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard `
-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' `
-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' `
-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' `
Expand Down
9 changes: 5 additions & 4 deletions src/frontend/src/content/docs/dashboard/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ The Aspire dashboard is also shipped as a Docker image and can be used standalon
<div slot="unix">

```bash
docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard \
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard \
mcr.microsoft.com/dotnet/aspire-dashboard:latest
```

</div>
<div slot="windows">

```powershell
docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard `
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest
```

Expand All @@ -55,9 +55,10 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard `
The preceding Docker command:

- Starts a container from the `mcr.microsoft.com/dotnet/aspire-dashboard:latest` image.
- The container instance exposing two ports:
- Maps the dashboard's OTLP port `18889` to the host's port `4317`. Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).
- The container instance exposing three ports:
- Maps the dashboard's port `18888` to the host's port `18888`. Port `18888` has the dashboard UI. Navigate to `http://localhost:18888` in the browser to view the dashboard.
- Maps 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).
- Maps 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).

For more information, see the [Standalone Aspire dashboard](/dashboard/standalone/).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ API key authentication can be enabled on the telemetry endpoint with some additi
<div slot="unix">

```bash
docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
docker run --rm -it -d -p 18888:18888 -p 4317:18889 -p 4318:18890 --name aspire-dashboard \
-e DASHBOARD__OTLP__AUTHMODE='ApiKey' \
-e DASHBOARD__OTLP__PRIMARYAPIKEY='{MY_APIKEY}' \
mcr.microsoft.com/dotnet/aspire-dashboard:latest
Expand All @@ -67,7 +67,7 @@ docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
<div slot="windows">

```powershell
docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard `
docker run --rm -it -d -p 18888:18888 -p 4317:18889 -p 4318:18890 --name aspire-dashboard `
-e DASHBOARD__OTLP__AUTHMODE='ApiKey' `
-e DASHBOARD__OTLP__PRIMARYAPIKEY='{MY_APIKEY}' `
mcr.microsoft.com/dotnet/aspire-dashboard:latest
Expand All @@ -78,7 +78,7 @@ docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard `

The preceding Docker command:

- Starts the Aspire dashboard image and exposes OTLP endpoint as port 4317
- Starts the Aspire dashboard image and exposes OTLP endpoints as port `4317` (gRPC) and port `4318` (HTTP)
- Configures the OTLP endpoint to use `ApiKey` authentication. This requires that incoming telemetry has a valid `x-otlp-api-key` header value.
- Configures the expected API key. `{MY_APIKEY}` in the example value should be replaced with a real API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended.

Expand All @@ -101,7 +101,7 @@ When enabled, the telemetry API is served on the same endpoint as the dashboard
<div slot="unix">

```bash
docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
docker run --rm -it -d -p 18888:18888 -p 4317:18889 -p 4318:18890 --name aspire-dashboard \
-e DASHBOARD__API__ENABLED='true' \
-e DASHBOARD__API__AUTHMODE='ApiKey' \
-e DASHBOARD__API__PRIMARYAPIKEY='{MY_APIKEY}' \
Expand All @@ -112,7 +112,7 @@ docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
<div slot="windows">

```powershell
docker run --rm -it -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard `
docker run --rm -it -d -p 18888:18888 -p 4317:18889 -p 4318:18890 --name aspire-dashboard `
-e DASHBOARD__API__ENABLED='true' `
-e DASHBOARD__API__AUTHMODE='ApiKey' `
-e DASHBOARD__API__PRIMARYAPIKEY='{MY_APIKEY}' `
Expand Down
23 changes: 16 additions & 7 deletions src/frontend/src/content/docs/dashboard/standalone.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ The dashboard is started using the Docker command line.
docker run --rm -it -d \
-p 18888:18888 \
-p 4317:18889 \
-p 4318:18890 \
--name aspire-dashboard \
mcr.microsoft.com/dotnet/aspire-dashboard:latest
```
Expand All @@ -43,6 +44,7 @@ docker run --rm -it -d \
docker run --rm -it -d `
-p 18888:18888 `
-p 4317:18889 `
-p 4318:18890 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest
```
Expand All @@ -53,9 +55,10 @@ docker run --rm -it -d `
The preceding Docker command:

- Starts a container from the `mcr.microsoft.com/dotnet/aspire-dashboard:latest` image.
- The container exposes two ports:
- Mapping the dashboard's OTLP port `18889` to the host's port `4317`. Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).
- The container exposes three ports:
- Mapping the dashboard's port `18888` to the host's port `18888`. Port `18888` has the dashboard UI. Navigate to `http://localhost:18888` in the browser to view the dashboard.
- 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).

## Login to the dashboard

Expand Down Expand Up @@ -126,23 +129,29 @@ The dashboard has functionality for viewing Aspire resources. The dashboard reso

Apps send telemetry to the dashboard using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/). The dashboard must expose a port for receiving OpenTelemetry data, and apps are configured to send data to that address.

A Docker command was shown earlier to [start the dashboard](#start-the-dashboard). It configured the container to receive OpenTelemetry data on port `4317`. The OTLP endpoint's full address is `http://localhost:4317`.
A Docker command was shown earlier to [start the dashboard](#start-the-dashboard). It configured the container to receive OpenTelemetry data on port `4317` (gRPC) and port `4318` (HTTP). The OTLP endpoint addresses are `http://localhost:4317` for gRPC and `http://localhost:4318` for HTTP.

### Configure OpenTelemetry SDK

Apps collect and send telemetry using [their language's OpenTelemetry SDK](https://opentelemetry.io/docs/languages/).

Important OpenTelemetry SDK options to configure:

- OTLP endpoint, which should match the dashboard's configuration, for example, `http://localhost:4317`.
- OTLP protocol, with the dashboard currently supporting only the [OTLP/gRPC protocol](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). Configure applications to use the `grpc` protocol.
- OTLP endpoint, which should match the dashboard's configuration, for example, `http://localhost:4317` for gRPC or `http://localhost:4318` for HTTP.
- OTLP protocol. The dashboard supports all OTLP protocols:
- [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) (`grpc`)
- [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) (`http/protobuf` or `http/json`)

To configure applications:

- Use the OpenTelemetry SDK APIs within the application, or
- Start the app with [known environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options):
- `OTEL_EXPORTER_OTLP_PROTOCOL` with a value of `grpc`.
- `OTEL_EXPORTER_OTLP_ENDPOINT` with a value of `http://localhost:4317`.
- `OTEL_EXPORTER_OTLP_PROTOCOL` with a value of `grpc`, `http/protobuf`, or `http/json`.
- `OTEL_EXPORTER_OTLP_ENDPOINT` with a value of `http://localhost:4317` for gRPC or `http://localhost:4318` for HTTP.

<Aside type="note">
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).
</Aside>

## Sample

Expand Down