Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added OTLP dashboard bits #1616

Merged
merged 8 commits into from
Sep 11, 2024
Merged

Added OTLP dashboard bits #1616

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7217a8c
Added OTLP dashboard bits
IEvangelist Sep 10, 2024
daeca8c
Demote a few headings
IEvangelist Sep 10, 2024
92abd74
Edit pass
IEvangelist Sep 10, 2024
8c9b02c
Apply suggestions from code review
IEvangelist Sep 11, 2024
59df278
Add an alert about allow methods
IEvangelist Sep 11, 2024
c2cb6b4
Addressing feedback
IEvangelist Sep 11, 2024
37df210
Fix alert syntax
IEvangelist Sep 11, 2024
0d01914
Update table
IEvangelist Sep 11, 2024
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
58 changes: 43 additions & 15 deletions docs/fundamentals/dashboard/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: .NET Aspire dashboard configuration
description: .NET Aspire dashboard configuration options
ms.date: 05/30/2024
ms.date: 09/10/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.
Expand Down Expand Up @@ -62,7 +62,7 @@ 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 |
|--|--|--|
Expand All @@ -73,26 +73,26 @@ Alternatively, these same values could be configured using a JSON configuration
| `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). |
| `Authentication:Schemes:OpenIdConnect:ClientId` | `null` | Identity of the relying party (RP). |
| `Authentication:Schemes:OpenIdConnect:ClientSecret` | `null` | A secret that only the real RP would know. |
| Other properties of <xref:Microsoft.AspNetCore.Builder.OpenIdConnectOptions> | `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.

Expand All @@ -102,9 +102,37 @@ 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) is a mechanism that allows many resources (for example, fonts, JavaScript, etc.) on a web page to be requested from another domain outside the domain from which the resource originated.

With the .NET Aspire dashboard, the OTLP endpoint can be configured to allow cross-origin requests. This is useful when the dashboard is hosted on a different domain than the OTLP endpoint, and this can enable scenarios where browser telemetry is sent directly to the OTLP endpoint as demonstrated in the [browser telemetry](https://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry) sample.
IEvangelist marked this conversation as resolved.
Show resolved Hide resolved
IEvangelist marked this conversation as resolved.
Show resolved Hide resolved

To configure CORS, use the `Dashboard:Otlp:Cors` section and specify the allowed origins and headers:

```json
{
"Dashboard": {
"Otlp": {
"Cors": {
"AllowedOrigins": [ "https://example.com" ],
"AllowedHeaders": [ "Content-Type" ]
IEvangelist marked this conversation as resolved.
Show resolved Hide resolved
}
}
}
}
```

Consider the following configuration options:

| Option | Default Value | Description |
|--|--|--|
| `DASHBOARD__OTLP__CORS__ALLOWEDORIGINS` | `null` | A comma-delimited list of allowed origins for CORS. This setting is optional and a shortcut to `Dashboard:Otlp:Cors:AllowedOrigins`. |
IEvangelist marked this conversation as resolved.
Show resolved Hide resolved
| `DASHBOARD__OTLP__CORS__ALLOWEDHEADERS` | `null` | A comma-delimited list of allowed headers for CORS. This setting is optional and a shortcut to `Dashboard:Otlp:Cors:AllowedHeaders`. |

## 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.

Expand All @@ -122,7 +150,7 @@ The resource service client authentication is configured with `Dashboard:Resourc
| `Dashboard:ResourceServiceClient:ClientCertificate:Store` | `My` | The certificate <xref:System.Security.Cryptography.X509Certificates.StoreName>. |
| `Dashboard:ResourceServiceClient:ClientCertificate:Location` | `CurrentUser` | The certificate <xref:System.Security.Cryptography.X509Certificates.StoreLocation>. |

#### 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.

Expand All @@ -140,7 +168,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 |
|--|--|--|
Expand Down
Loading