Enable browser telemetry

The Aspire dashboard can be configured to receive telemetry sent from browser apps. This feature is useful for monitoring client-side performance and user interactions. Browser telemetry requires additional dashboard configuration. Generic JavaScript browser apps also need the JavaScript OTEL SDK; Blazor WebAssembly apps should use the Aspire Blazor hosting gateway/proxy support.

This article discusses how to configure the Aspire dashboard to receive browser telemetry. For information on configuring the browser app itself, see Browser app configuration. For Blazor WebAssembly apps, see Blazor WebAssembly integration.

Dashboard configuration

Browser telemetry requires the dashboard to enable these features:

OTLP HTTP endpoint. This endpoint is used by the dashboard to receive telemetry from browser apps.
Cross-origin resource sharing (CORS). CORS allows browser apps to make requests to the dashboard.

OTLP configuration

The Aspire dashboard receives telemetry through OTLP endpoints. HTTP OTLP endpoints and gRPC OTLP endpoints are supported by the dashboard. Browser apps must use HTTP OTLP to send telemetry to the dashboard because browser apps don’t support gRPC.

To configure the gRPC or HTTP endpoints, specify the following environment variables:

ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL: The gRPC endpoint to which the dashboard connects for its data.
ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL: The HTTP endpoint to which the dashboard connects for its data.

Configuration of the HTTP OTLP endpoint depends on whether the dashboard is started by the AppHost or is run standalone.

Configure OTLP HTTP with AppHost

If the dashboard and your app are started by the AppHost, the dashboard OTLP endpoints are configured in the AppHost’s launchSettings.json file.

Consider the following example launchSettings.json file:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:15887;http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16175",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037",
        "ASPIRE_SHOW_DASHBOARD_RESOURCES": "true"
      }
    },
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http://localhost:16175",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17037",
        "ASPIRE_SHOW_DASHBOARD_RESOURCES": "true",
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    },
    "generate-manifest": {
      "commandName": "Project",
      "launchBrowser": true,
      "dotnetRunMessages": true,
      "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json",
      "applicationUrl": "http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development"
      }
    }
  }
}

The preceding launch settings JSON file configures all profiles to include the ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL environment variable.

Configure OTLP HTTP with standalone dashboard

If the dashboard is used standalone, without the rest of Aspire, the OTLP HTTP endpoint is enabled by default on port 18890. However, the port must be mapped when the dashboard container is started:

Bash
PowerShell

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

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

The preceding command runs the dashboard container and maps gRPC OTLP to port 4317 and HTTP OTLP to port 4318.

CORS configuration

By default, browser apps are restricted from making cross-domain API calls. This impacts sending telemetry to the dashboard because the dashboard and the browser app are always on different domains. Configuring CORS in the Aspire dashboard removes the restriction.

If the dashboard and your app are started by the AppHost, no CORS configuration is required. Aspire automatically configures the dashboard to allow all resource origins.

If the dashboard is used standalone, then CORS must be configured manually. The domain used to view the browser app must be configured as an allowed origin by specifying the DASHBOARD__OTLP__CORS__ALLOWEDORIGINS environment variable when the dashboard container is started.

Bash
PowerShell

docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    -p 4318:18890 \
    -e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

docker run --rm -it -d `
    -p 18888:18888 `
    -p 4317:18889 `
    -p 4318:18890 `
    -e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 `
    --name aspire-dashboard `
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

The preceding command runs the dashboard container and configures https://localhost:8080 as an allowed origin. That means a browser app that is accessed using https://localhost:8080 has permission to send the dashboard telemetry.

Multiple origins can be allowed with a comma-separated value. Or all origins can be allowed with the * wildcard. For example, DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=*.

For more information, see Aspire dashboard configuration: OTLP CORS.

OTLP endpoint security

Dashboard OTLP endpoints can be secured with API key authentication. When enabled, HTTP OTLP requests to the dashboard must include the API key as the x-otlp-api-key header. By default a new API key is generated each time the dashboard is run.

API key authentication is automatically enabled when the dashboard is run from the AppHost. Dashboard authentication can be disabled by setting ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS to true in the AppHost’s launchSettings.json file.

OTLP endpoints are unsecured by default in the standalone dashboard.

Next steps

Browser app configurationConfigure a generic JavaScript browser app to send OTLP telemetry to the dashboard.

Blazor WebAssembly integrationUse Aspire Blazor hosting to proxy Blazor WebAssembly telemetry through the app gateway.