-
Notifications
You must be signed in to change notification settings - Fork 94
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1820 from dotnet/main
✅ Merge `main` into `live`
- Loading branch information
Showing
40 changed files
with
2,775 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
163 changes: 163 additions & 0 deletions
163
docs/fundamentals/dashboard/enable-browser-telemetry.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,163 @@ | ||
--- | ||
title: Enable browser telemetry | ||
description: Learn how to enable browser telemetry in the .NET Aspire dashboard. | ||
ms.date: 10/11/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: | ||
|
||
### [Bash](#tab/bash) | ||
|
||
```bash | ||
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 | ||
``` | ||
|
||
### [PowerShell](#tab/powershell) | ||
|
||
```powershell | ||
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: | ||
|
||
### [Bash](#tab/bash) | ||
|
||
```bash | ||
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 | ||
``` | ||
|
||
### [PowerShell](#tab/powershell) | ||
|
||
```powershell | ||
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://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry). | ||
|
||
## See also | ||
|
||
- [.NET Aspire dashboard configuration](configuration.md) | ||
- [Standalone .NET Aspire dashboard](standalone.md) | ||
- [Browser telemetry sample](https://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
17 changes: 17 additions & 0 deletions
17
...hboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/BrowserTelemetry.AppHost.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
6 changes: 6 additions & 0 deletions
6
docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Program.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
var builder = DistributedApplication.CreateBuilder(args); | ||
|
||
builder.AddProject<Projects.BrowserTelemetry_Web>("web") | ||
.WithExternalHttpEndpoints(); | ||
|
||
builder.Build().Run(); |
43 changes: 43 additions & 0 deletions
43
...shboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Properties/launchSettings.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
{ | ||
"$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" | ||
} | ||
} | ||
} | ||
} |
8 changes: 8 additions & 0 deletions
8
...dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/appsettings.Development.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
{ | ||
"Logging": { | ||
"LogLevel": { | ||
"Default": "Information", | ||
"Microsoft.AspNetCore": "Warning" | ||
} | ||
} | ||
} |
9 changes: 9 additions & 0 deletions
9
...undamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.AppHost/appsettings.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
{ | ||
"Logging": { | ||
"LogLevel": { | ||
"Default": "Information", | ||
"Microsoft.AspNetCore": "Warning", | ||
"Aspire.Hosting.Dcp": "Warning" | ||
} | ||
} | ||
} |
22 changes: 22 additions & 0 deletions
22
...BrowserTelemetry/BrowserTelemetry.ServiceDefaults/BrowserTelemetry.ServiceDefaults.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
<Project Sdk="Microsoft.NET.Sdk"> | ||
|
||
<PropertyGroup> | ||
<TargetFramework>net8.0</TargetFramework> | ||
<ImplicitUsings>enable</ImplicitUsings> | ||
<Nullable>enable</Nullable> | ||
<IsAspireSharedProject>true</IsAspireSharedProject> | ||
</PropertyGroup> | ||
|
||
<ItemGroup> | ||
<FrameworkReference Include="Microsoft.AspNetCore.App" /> | ||
|
||
<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="8.8.0" /> | ||
<PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="8.2.0" /> | ||
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" /> | ||
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" /> | ||
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" /> | ||
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" /> | ||
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.9.0" /> | ||
</ItemGroup> | ||
|
||
</Project> |
Oops, something went wrong.