Add a link and sentence about browser telemetry.

.gitignore

@@ -1,3 +1,5 @@
+syntax: glob
+
 # Python virtual environments
 .venv
 
@@ -59,4 +61,6 @@ docs/core/extensions/snippets/workers/cloud-service/Properties/PublishProfiles/c
 docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.xml
 
 BenchmarkDotNet.Artifacts
-*.pfx
+*.pfx
+
+node_modules/

docs/fundamentals/dashboard/configuration.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire dashboard configuration
 description: .NET Aspire dashboard configuration options
-ms.date: 09/11/2024
+ms.date: 10/03/2024
 ms.topic: reference
 ---
 
@@ -71,7 +71,7 @@ Alternatively, these same values could be configured using a JSON configuration
 | `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`. |
+| `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:ResourceService:Url`. |
 
 ## Frontend authentication
 
@@ -108,11 +108,7 @@ API key authentication works by requiring each OTLP request to have a valid `x-o
 
 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:/dotnet/aspire/tree/main/playground/BrowserTelemetry) sample.
-
-To configure CORS, use the `Dashboard:Otlp:Cors` section and specify the allowed origins and headers:
+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. To configure CORS, use the `Dashboard:Otlp:Cors` section and specify the allowed origins and headers:
 
 ```json
 {
@@ -140,19 +136,19 @@ Consider the following configuration options:
 
 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.
 
-The resource service client authentication is configured with `Dashboard:ResourceServiceClient:AuthMode`. The client can be configured to support API key or client certificate authentication.
+The resource service client authentication is configured with `Dashboard:ResourceService:AuthMode`. The client can be configured to support API key or client certificate authentication.
 
 | Option | Default Value | Description |
 |--|--|--|
-| `Dashboard:ResourceServiceClient: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. |
-| `Dashboard:ResourceServiceClient:AuthMode` | `null` | 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. This value is required if a resource service URL is specified. |
-| `Dashboard:ResourceServiceClient:ApiKey` | `null` | The API to send to the resource service in the `x-resource-service-api-key` header. This value is required if auth mode is API key. |
-| `Dashboard:ResourceServiceClient:ClientCertificate:Source` | `null` | Can be set to `File` or `KeyStore`. This value is required if auth mode is client certificate. |
-| `Dashboard:ResourceServiceClient:ClientCertificate:FilePath` | `null` | The certificate file path. This value is required if source is `File`. |
-| `Dashboard:ResourceServiceClient:ClientCertificate:Password` | `null` | The password for the certificate file. This value is optional. |
-| `Dashboard:ResourceServiceClient:ClientCertificate:Subject` | `null` | The certificate subject. This value is required if source is `KeyStore`. |
-| `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>. |
+| `Dashboard:ResourceService: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. |
+| `Dashboard:ResourceService:AuthMode` | `null` | 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. This value is required if a resource service URL is specified. |
+| `Dashboard:ResourceService:ApiKey` | `null` | The API to send to the resource service in the `x-resource-service-api-key` header. This value is required if auth mode is API key. |
+| `Dashboard:ResourceService:ClientCertificate:Source` | `null` | Can be set to `File` or `KeyStore`. This value is required if auth mode is client certificate. |
+| `Dashboard:ResourceService:ClientCertificate:FilePath` | `null` | The certificate file path. This value is required if source is `File`. |
+| `Dashboard:ResourceService:ClientCertificate:Password` | `null` | The password for the certificate file. This value is optional. |
+| `Dashboard:ResourceService:ClientCertificate:Subject` | `null` | The certificate subject. This value is required if source is `KeyStore`. |
+| `Dashboard:ResourceService:ClientCertificate:Store` | `My` | The certificate <xref:System.Security.Cryptography.X509Certificates.StoreName>. |
+| `Dashboard:ResourceService:ClientCertificate:Location` | `CurrentUser` | The certificate <xref:System.Security.Cryptography.X509Certificates.StoreLocation>. |
 
 ### Telemetry limits
 

docs/fundamentals/dashboard/enable-browser-telemetry.md

@@ -0,0 +1,132 @@
+---
+title: Enable browser telemetry
+description: Learn how to enable browser telemetry in the .NET Aspire dashboard.
+ms.date: 10/03/2024
+---
+
+# Enable browser telemetry
+
+The .NET Aspire dashboard can be configure to receive telemetry sent from browser apps. This feature is useful for monitoring client-side performance and user interactions. Browser telemetry requires additional configuration to setup. This article discusses how to enable browser telemetry in the .NET Aspire dashboard.
+
+In addition to [enabling CORS](configuration.md#otlp-cors), you also need the [JavaScript OTEL SDK](https://opentelemetry.io/docs/languages/js/getting-started/browser/) in your browser app.
+
+## OTLP configuration
+
+The .NET Aspire dashboard receives telemetry through OTLP endpoints. [HTTP OTLP endpoints](https://opentelemetry.io/docs/specs/otlp/#otlphttp) and gRPC OTLP endpoints are supported by the dashboard. Browser apps must use HTTP OLTP to send telemetry to the dashboard because browser apps don't support gRPC.
+
+To configure the gPRC or HTTP endpoints, specify the following environment variables:
+
+- `DOTNET_DASHBOARD_OTLP_ENDPOINT_URL`: The gRPC endpoint to which the dashboard connects for its data.
+- `DOTNET_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 app host or is run standalone.
+
+### Configure OTLP HTTP with app host
+
+If the dashboard and your app are started by the app host, the dashboard OTLP endpoints are configured in the app host's _launchSettings.json_ file.
+
+Consider the following example JSON file:
+
+:::code language="json" source="snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Properties/launchSettings.json" highlight="12,25,40":::
+
+The preceding launch settings JSON file configures all profiles to include the `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` environment variable.
+
+### Configure OTLP HTTP with standalone dashboard
+
+If the dashboard is used standalone, without the rest of .NET Aspire, the OTLP HTTP endpoint is enabled by default on port `18890`. However, the port must be mapped when the dashboard container is started:
+
+```
+docker run --rm -it \
+ -p 18888:18888 \
+ -p 4317:18889 \
+ -p 4318:18890 -d \
+ --name aspire-dashboard \
+ mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
+```
+
+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 .NET Aspire dashboard removes the restriction.
+
+If the dashboard and your app are started by the app host, no CORS configuration is required. .NET Aspire automatically configures the dashboard to allow all resource origins.
+
+If the dashboard is used standlone then CORS must be configured manually. The domain used to view the browser app must be configured as an allowed origin by specifing the `DASHBOARD__OTLP__CORS__ALLOWEDORIGINS` environment variable when the dashboard container is started:
+
+```
+docker run --rm -it \
+ -p 18888:18888 \
+ -p 4317:18889 \
+ -p 4318:18890 -d \
+ -e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 \
+ --name aspire-dashboard \
+ mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
+```
+
+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 [.NET Aspire dashboard configuration: OTLP CORS](configuration.md#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 app host. Dashboard authentication can be disabled by setting `DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` to `true` in the app host's _launchSettings.json_ file.
+
+OTLP endpoints are unsecured by default in the standalone dashboard.
+
+## Browser app configuration
+
+A browser app uses the [JavaScript OTEL SDK](https://opentelemetry.io/docs/languages/js/getting-started/browser/) to send telemetry to the dashboard. Successfully sending telemetry to the dashboard requires the SDK to be correctly configured.
+
+### OTLP exporter
+
+OTLP exporters must be included in the browser app and configured with the SDK. For example, exporting distributed tracing with OTLP uses the [@opentelemetry/exporter-trace-otlp-proto](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto) package.
+
+When OTLP is added to the SDK, OTLP options must be specified. OTLP options includes:
+
+- `url`: The address that HTTP OTLP requests are made to. The address should be the dashboard HTTP OTLP endpoint and the path to the OTLP HTTP API. For example, `https://localhost:4318/v1/traces` for the trace OTLP exporter. If the browser app is launched by the app host then the HTTP OTLP endpoint is available from the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable.
+
+- `headers`: The headers sent with requests. If OTLP endpoint API key authentication is enabled the `x-otlp-api-key` header must be sent with OTLP requests. If the browser app is launched by the app host then the API key is available from the `OTEL_EXPORTER_OTLP_HEADERS` environment variable.
+
+### Browser metadata
+
+When a browser app is configured to collect distributed traces, the browser app can set the trace parent a browser's spans using the `meta` element in the HTML. The value of the `name="traceparent"` meta element should correspond to the current trace.
+
+In a .NET app, for example, the trace parent value would likely be assigned from the <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType> and passing its <xref:System.Diagnostics.Activity.Id?displayProperty=nameWithType> value as the `content`. For example, consider the following Razor code:
+
+```razor
+<head>
+ @if (Activity.Current is { } currentActivity)
+ {
+ <meta name="traceparent" content="@currentActivity.Id" />
+ }
+ <!-- Other elements omitted for brevity... -->
+</head>
+```
+
+The preceding code sets the `traceparent` meta element to the current activity ID.
+
+## Example browser telemetry code
+
+The following JavaScript code demonstrates the initialization of the OpenTelemetry JavaScript SDK and the sending of telemetry data to the dashboard:
+
+:::code language="javascript" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Scripts/index.js":::
+
+The preceding JavaScript code defines an `initializeTelemetry` function that expects the OTLP endpoint URL, the headers, and the resource attributes. These parameters are provided by the consuming browser app that pulls them from the environment variables set by the app host. Consider the following Razor code:
+
+:::code language="razor" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Pages/Shared/_Layout.cshtml" highlight="31-38":::
+
+> [!TIP]
+> The bundling and minification of the JavaScript code is beyond the scope of this article.
+
+For the complete working example of how to configure the JavaScript OTEL SDK to send telemetry to the dashboard, see the [browser telemetry sample](https:/dotnet/aspire/tree/main/playground/BrowserTelemetry).
+
+## See also
+
+- [.NET Aspire dashboard configuration](configuration.md)
+- [Standalone .NET Aspire dashboard](standalone.md)
+- [Browser telemetry sample](https:/dotnet/aspire/tree/main/playground/BrowserTelemetry)

docs/fundamentals/dashboard/overview.md

@@ -1,15 +1,15 @@
 ---
 title: .NET Aspire dashboard overview
 description: Overview of .NET Aspire dashboard and getting started.
-ms.date: 05/30/2024
+ms.date: 10/03/2024
 ms.topic: reference
 ---
 
 # .NET Aspire dashboard overview
 
-[.NET Aspire](../../get-started/aspire-overview.md) project templates offer a sophisticated dashboard for comprehensive app monitoring and inspection. This dashboard allows you to closely track various aspects of your app, including logs, traces, and environment configurations, in real-time. It's purpose-built to enhance the local development experience, providing an insightful overview of your app's state and structure.
+[.NET Aspire](../../get-started/aspire-overview.md) project templates offer a sophisticated dashboard for comprehensive app monitoring and inspection, and it's also available in [standalone mode](#standalone-mode). This dashboard allows you to closely track various aspects of your app, including logs, traces, and environment configurations, in real-time. It's purpose-built to enhance the development experience, providing an insightful overview of your app's state and structure.
 
-## Using the dashboard with .NET Aspire projects
+## Use the dashboard with .NET Aspire projects
 
 The dashboard is integrated into the .NET Aspire **AppHost**. During development the dashboard is automatically launched when you start the project. It's configured to display the .NET Aspire project's resources and telemetry.
 

docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/BrowserTelemetry.AppHost.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+ <PropertyGroup>
+ <OutputType>Exe</OutputType>
+ <TargetFramework>net8.0</TargetFramework>
+ <ImplicitUsings>enable</ImplicitUsings>
+ <Nullable>enable</Nullable>
+ <IsAspireHost>true</IsAspireHost>
+ <UserSecretsId>7247ba20-5e3e-4299-afa7-4ca58ebe3488</UserSecretsId>
+ </PropertyGroup>
+
+ <ItemGroup>
+ <PackageReference Include="Aspire.Hosting.AppHost" Version="8.2.0" />
+ <ProjectReference Include="..\BrowserTelemetry.Web\BrowserTelemetry.Web.csproj" />
+ </ItemGroup>
+
+</Project>

docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Program.cs

@@ -0,0 +1,6 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddProject<Projects.BrowserTelemetry_Web>("web")
+ .WithExternalHttpEndpoints();
+
+builder.Build().Run();

docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Properties/launchSettings.json

@@ -0,0 +1,44 @@
+{
+ "$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",
+ "DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16175",
+ "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037",
+ "DOTNET_ASPIRE_SHOW_DASHBOARD_RESOURCES": "true"
+ }
+ },
+ "http": {
+ "commandName": "Project",
+ "dotnetRunMessages": true,
+ "launchBrowser": true,
+ "applicationUrl": "http://localhost:15888",
+ "environmentVariables": {
+ "ASPNETCORE_ENVIRONMENT": "Development",
+ "DOTNET_ENVIRONMENT": "Development",
+ "DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http://localhost:16175",
+ "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17037",
+ "DOTNET_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",
+ "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16175"
+ }
+ }
+ }
+}

docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+ "Logging": {
+ "LogLevel": {
+ "Default": "Information",
+ "Microsoft.AspNetCore": "Warning"
+ }
+ }
+}

docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+ "Logging": {
+ "LogLevel": {
+ "Default": "Information",
+ "Microsoft.AspNetCore": "Warning",
+ "Aspire.Hosting.Dcp": "Warning"
+ }
+ }
+}