From db14b34765fa366eae5ac5637ef26bf096d1ab7c Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 11 Sep 2024 09:50:31 -0500 Subject: [PATCH] Added OTLP dashboard bits (#1616) * Added OTLP dashboard bits * Demote a few headings * Edit pass * Apply suggestions from code review Co-authored-by: James Newton-King * Add an alert about allow methods * Addressing feedback * Fix alert syntax * Update table --------- Co-authored-by: James Newton-King --- docs/fundamentals/dashboard/configuration.md | 64 +++++++++++++++----- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index 1f64f36ee2..3c50774a71 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -1,17 +1,17 @@ --- title: .NET Aspire dashboard configuration description: .NET Aspire dashboard configuration options -ms.date: 05/30/2024 +ms.date: 09/11/2024 ms.topic: reference --- # Dashboard configuration -The dashboard is configured when it starts up. Configuration includes frontend and OTLP addresses, the resource service endpoint, authentication, telemetry limits, and more. +The dashboard is configured when it starts up. Configuration includes frontend and OpenTelemetry Protocol (OTLP) addresses, the resource service endpoint, authentication, telemetry limits, and more. -If the dashboard is launched by the .NET Aspire app host project, then it's automatically configured to display the app's resources and telemetry. Configuration is provided when launching the dashboard in [standalone mode](overview.md#standalone-mode). +When the dashboard is launched with the .NET Aspire app host project, it's automatically configured to display the app's resources and telemetry. Configuration is provided when launching the dashboard in [standalone mode](overview.md#standalone-mode). -There are a number of ways to provide configuration: +There are many ways to provide configuration: - Command line arguments. - Environment variables. The `:` delimiter should be replaced with double underscore (`__`) in environment variable names. @@ -62,29 +62,29 @@ Alternatively, these same values could be configured using a JSON configuration > > For more information, see [dashboard security](security-considerations.md). -### Common configuration +## Common configuration | Option | Default Value | Description | |--|--|--| | `ASPNETCORE_URLS` | `http://localhost:18888` | One or more HTTP endpoints through which the dashboard frontend is served. The frontend endpoint is used to view the dashboard in a browser. When the dashboard is launched by the .NET Aspire app host this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | | `DOTNET_DASHBOARD_OTLP_ENDPOINT_URL` | `http://localhost:18889` | The [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) endpoint. This endpoint hosts an OTLP service and receives telemetry using gRPC. When the dashboard is launched by the .NET Aspire app host this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | -| `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` | `http://localhost:18890` | The [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. When the dashboard is launched by the .NET Aspire app host the OTLP/HTTP endpoint isn't configured by default. To configure an OTLP/HTTP endpoint with the app host, set an `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` env var value in `launchSettings.json`. Securing the dashboard with HTTPS is recommended. | +| `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` | `http://localhost:18890` | The [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. When the dashboard is launched by the .NET Aspire app host the OTLP/HTTP endpoint isn't configured by default. To configure an OTLP/HTTP endpoint with the app host, set an `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` env var value in _launchSettings.json_. Securing the dashboard with HTTPS is recommended. | | `DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` | `false` | Configures the dashboard to not use authentication and accepts anonymous access. This setting is a shortcut to configuring `Dashboard:Frontend:AuthMode` and `Dashboard:Otlp:AuthMode` to `Unsecured`. | | `DOTNET_DASHBOARD_CONFIG_FILE_PATH` | `null` | The path for a JSON configuration file. If the dashboard is being run in a Docker container, then this is the path to the configuration file in a mounted volume. This value is optional. | | `DOTNET_RESOURCE_SERVICE_ENDPOINT_URL` | `null` | The gRPC endpoint to which the dashboard connects for its data. If this value is unspecified, the dashboard shows telemetry data but no resource list or console logs. This setting is a shortcut to `Dashboard:ResourceServiceClient:Url`. | -### Frontend authentication +## Frontend authentication The dashboard frontend endpoint authentication is configured with `Dashboard:Frontend:AuthMode`. The frontend can be secured with OpenID Connect (OIDC) or browser token authentication. -Browser token authentication works by the frontend asking for a token. The token can either be entered in the UI or provided as a query string value to the login page. For example, `https://localhost:1234/login?t=TheToken`. When the token is successfully authenticated an auth cookie is persisted to the browser and the browser is redirected to the app. +Browser token authentication works by the frontend asking for a token. The token can either be entered in the UI or provided as a query string value to the login page. For example, `https://localhost:1234/login?t=TheToken`. When the token is successfully authenticated an auth cookie is persisted to the browser, and the browser is redirected to the app. | Option | Default Value | Description | |--|--|--| | `Dashboard:Frontend:AuthMode` | `BrowserToken` | Can be set to `BrowserToken`, `OpenIdConnect` or `Unsecured`. `Unsecured` should only be used during local development. It's not recommended when hosting the dashboard publicly or in other settings. | -| `Dashboard:Frontend:BrowserToken` | `null` | Specifies the browser token. If the browser token isn't specified, then the dashboard will generate one. Tooling that wants to automate logging in with browser token authentication can specify a token and open a browser with the token in the query string. A new token should be generated each time the dashboard is launched. | -| `Dashboard:Frontend:OpenIdConnect:NameClaimType` | `name` | Specifies the claim type(s) that should be used to display the authenticated user's full name. Can be a single claim type or a comma-delimited list of claim types. | -| `Dashboard:Frontend:OpenIdConnect:UsernameClaimType` | `preferred_username` | Specifies the claim type(s) that should be used to display the authenticated user's username. Can be a single claim type or a comma-delimited list of claim types. | +| `Dashboard:Frontend:BrowserToken` | `null` | Specifies the browser token. If the browser token isn't specified, then the dashboard generates one. Tooling that wants to automate logging in with browser token authentication can specify a token and open a browser with the token in the query string. A new token should be generated each time the dashboard is launched. | +| `Dashboard:Frontend:OpenIdConnect:NameClaimType` | `name` | Specifies one or more claim types that should be used to display the authenticated user's full name. Can be a single claim type or a comma-delimited list of claim types. | +| `Dashboard:Frontend:OpenIdConnect:UsernameClaimType` | `preferred_username` | Specifies one or more claim types that should be used to display the authenticated user's username. Can be a single claim type or a comma-delimited list of claim types. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimType` | `null` | Specifies the claim that must be present for authorized users. Authorization fails without this claim. This value is optional. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimValue` | `null` | Specifies the value of the required claim. Only used if `Dashboard:Frontend:OpenIdConnect:RequireClaimType` is also specified. This value is optional. | | `Authentication:Schemes:OpenIdConnect:Authority` | `null` | URL to the identity provider (IdP). | @@ -92,7 +92,7 @@ Browser token authentication works by the frontend asking for a token. The token | `Authentication:Schemes:OpenIdConnect:ClientSecret` | `null` | A secret that only the real RP would know. | | Other properties of | `null` | Values inside configuration section `Authentication:Schemes:OpenIdConnect:*` are bound to `OpenIdConnectOptions`, such as `Scope`. | -### OTLP authentication +## OTLP authentication The OTLP endpoint authentication is configured with `Dashboard:Otlp:AuthMode`. The OTLP endpoint can be secured with an API key or [client certificate](/aspnet/core/security/authentication/certauth) authentication. @@ -102,9 +102,41 @@ API key authentication works by requiring each OTLP request to have a valid `x-o |--|--|--| | `Dashboard:Otlp:AuthMode` | `Unsecured` | Can be set to `ApiKey`, `Certificate` or `Unsecured`. `Unsecured` should only be used during local development. It's not recommended when hosting the dashboard publicly or in other settings. | | `Dashboard:Otlp:PrimaryApiKey` | `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:Otlp:SecondaryApiKey` | `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. If a second API key is specified then the incoming `x-otlp-api-key` header value can match either the primary or secondary key. | +| `Dashboard:Otlp:SecondaryApiKey` | `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. If a second API key is specified, then the incoming `x-otlp-api-key` header value can match either the primary or secondary key. | -### Resources +## OTLP CORS + +CORS (Cross-Origin Resource Sharing) can be configured to allow browser apps to send telemetry to the dashboard. + +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 .NET Aspire dashboard removes the restriction and allows browser apps with the [OpenTelemetry SDK for JavaScript](https://opentelemetry.io/docs/languages/js/) to send telemetry directly to the dashboard OTLP HTTP endpoint. + +Using CORS, the dashboard and browser telemetry together is demonstrated in the [browser telemetry](https://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry) sample. + +To configure CORS, use the `Dashboard:Otlp:Cors` section and specify the allowed origins and headers: + +```json +{ + "Dashboard": { + "Otlp": { + "Cors": { + "AllowedOrigins": "http://localhost:5000,https://localhost:5001" + } + } + } +} +``` + +Consider the following configuration options: + +| Option | Default Value | Description | +|--|--|--| +| `Dashboard:Otlp:Cors:AllowedOrigins` | `null` | Specifies the allowed origins for CORS. It's a comma-delimited string and can include the `*` wildcard to allow any domain. This option is optional and can be set using the `DASHBOARD__OTLP__CORS__ALLOWEDORIGINS` environment variable. | +| `Dashboard:Otlp:Cors:AllowedHeaders` | `null` | A comma-delimited string representing the allowed headers for CORS. This setting is optional and can be set using the `DASHBOARD__OTLP__CORS__ALLOWEDHEADERS` environment variable. | + +> [!NOTE] +> The dashboard only supports the `POST` method for sending telemetry and doesn't allow configuration of the _allowed methods_ (`Access-Control-Allow-Methods`) for CORS. + +## Resources The dashboard connects to a resource service to load and display resource information. The client is configured in the dashboard for how to connect to the service. @@ -122,7 +154,7 @@ The resource service client authentication is configured with `Dashboard:Resourc | `Dashboard:ResourceServiceClient:ClientCertificate:Store` | `My` | The certificate . | | `Dashboard:ResourceServiceClient:ClientCertificate:Location` | `CurrentUser` | The certificate . | -#### Telemetry limits +### Telemetry limits Telemetry is stored in memory. To avoid excessive memory usage, the dashboard has limits on the count and size of stored telemetry. When a count limit is reached, new telemetry is added, and the oldest telemetry is removed. When a size limit is reached, data is truncated to the limit. @@ -140,7 +172,7 @@ Telemetry limits have different scopes depending upon the telemetry type: | `Dashboard:TelemetryLimits:MaxAttributeLength` | `null` | The maximum length of attributes. | | `Dashboard:TelemetryLimits:MaxSpanEventCount` | `null` | The maximum number of events on span attributes. | -### Other +## Other | Option | Default Value | Description | |--|--|--|