Skip to content

Commit 4f74ddf

Browse files
IEvangelistJamesNK
IEvangelist
and
JamesNK
authored
Add a link and sentence about browser telemetry. (#1701)
* Add a link and sentence about browser telemetry. * Try adding a bit more context and content around browser telemetry * Fix MD lint errors * Use highlight instead of range, and set scope * link to related content. * Better heading links * Added launch settings JSON bits * Add a few more bits * Prefer a new article * Fix heading link * A bit more * edit pass * Browser telemetry edits * Cherry-pick plus a few edits * Remove env var --------- Co-authored-by: James Newton-King <james@newtonking.com>
1 parent e76fd22 commit 4f74ddf

35 files changed

+2738
-10
lines changed

‎.gitignore

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
syntax: glob
2+
13
# Python virtual environments
24
.venv
35

@@ -59,4 +61,6 @@ docs/core/extensions/snippets/workers/cloud-service/Properties/PublishProfiles/c
5961
docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.xml
6062

6163
BenchmarkDotNet.Artifacts
62-
*.pfx
64+
*.pfx
65+
66+
node_modules/

‎docs/fundamentals/dashboard/configuration.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: .NET Aspire dashboard configuration
33
description: .NET Aspire dashboard configuration options
4-
ms.date: 09/11/2024
4+
ms.date: 10/03/2024
55
ms.topic: reference
66
---
77

@@ -108,11 +108,7 @@ API key authentication works by requiring each OTLP request to have a valid `x-o
108108

109109
CORS (Cross-Origin Resource Sharing) can be configured to allow browser apps to send telemetry to the dashboard.
110110

111-
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.
112-
113-
Using CORS, the dashboard and browser telemetry together is demonstrated in the [browser telemetry](https://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry) sample.
114-
115-
To configure CORS, use the `Dashboard:Otlp:Cors` section and specify the allowed origins and headers:
111+
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:
116112

117113
```json
118114
{

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: Enable browser telemetry
3+
description: Learn how to enable browser telemetry in the .NET Aspire dashboard.
4+
ms.date: 10/11/2024
5+
---
6+
7+
# Enable browser telemetry
8+
9+
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.
10+
11+
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.
12+
13+
## OTLP configuration
14+
15+
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.
16+
17+
To configure the gPRC or HTTP endpoints, specify the following environment variables:
18+
19+
- `DOTNET_DASHBOARD_OTLP_ENDPOINT_URL`: The gRPC endpoint to which the dashboard connects for its data.
20+
- `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL`: The HTTP endpoint to which the dashboard connects for its data.
21+
22+
Configuration of the HTTP OTLP endpoint depends on whether the dashboard is started by the app host or is run standalone.
23+
24+
### Configure OTLP HTTP with app host
25+
26+
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.
27+
28+
Consider the following example JSON file:
29+
30+
:::code language="json" source="snippets/BrowserTelemetry/BrowserTelemetry.AppHost/Properties/launchSettings.json" highlight="12,25,40":::
31+
32+
The preceding launch settings JSON file configures all profiles to include the `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` environment variable.
33+
34+
### Configure OTLP HTTP with standalone dashboard
35+
36+
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:
37+
38+
### [Bash](#tab/bash)
39+
40+
```bash
41+
docker run --rm -it \
42+
-p 18888:18888 \
43+
-p 4317:18889 \
44+
-p 4318:18890 -d \
45+
--name aspire-dashboard \
46+
mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
47+
```
48+
49+
### [PowerShell](#tab/powershell)
50+
51+
```powershell
52+
docker run --rm -it `
53+
-p 18888:18888 `
54+
-p 4317:18889 `
55+
-p 4318:18890 -d `
56+
--name aspire-dashboard `
57+
mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
58+
```
59+
60+
---
61+
62+
The preceding command runs the dashboard container and maps gRPC OTLP to port `4317` and HTTP OTLP to port `4318`.
63+
64+
## CORS configuration
65+
66+
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.
67+
68+
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.
69+
70+
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:
71+
72+
### [Bash](#tab/bash)
73+
74+
```bash
75+
docker run --rm -it \
76+
-p 18888:18888 \
77+
-p 4317:18889 \
78+
-p 4318:18890 -d \
79+
-e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 \
80+
--name aspire-dashboard \
81+
mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
82+
```
83+
84+
### [PowerShell](#tab/powershell)
85+
86+
```powershell
87+
docker run --rm -it `
88+
-p 18888:18888 `
89+
-p 4317:18889 `
90+
-p 4318:18890 -d `
91+
-e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 `
92+
--name aspire-dashboard `
93+
mcr.microsoft.com/dotnet/aspire-dashboard:8.1.0
94+
```
95+
96+
---
97+
98+
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.
99+
100+
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=*`.
101+
102+
For more information, see [.NET Aspire dashboard configuration: OTLP CORS](configuration.md#otlp-cors).
103+
104+
## OTLP endpoint security
105+
106+
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.
107+
108+
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.
109+
110+
OTLP endpoints are unsecured by default in the standalone dashboard.
111+
112+
## Browser app configuration
113+
114+
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.
115+
116+
### OTLP exporter
117+
118+
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.
119+
120+
When OTLP is added to the SDK, OTLP options must be specified. OTLP options includes:
121+
122+
- `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.
123+
124+
- `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.
125+
126+
### Browser metadata
127+
128+
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.
129+
130+
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:
131+
132+
```razor
133+
<head>
134+
@if (Activity.Current is { } currentActivity)
135+
{
136+
<meta name="traceparent" content="@currentActivity.Id" />
137+
}
138+
<!-- Other elements omitted for brevity... -->
139+
</head>
140+
```
141+
142+
The preceding code sets the `traceparent` meta element to the current activity ID.
143+
144+
## Example browser telemetry code
145+
146+
The following JavaScript code demonstrates the initialization of the OpenTelemetry JavaScript SDK and the sending of telemetry data to the dashboard:
147+
148+
:::code language="javascript" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Scripts/index.js":::
149+
150+
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:
151+
152+
:::code language="razor" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Pages/Shared/_Layout.cshtml" highlight="31-38":::
153+
154+
> [!TIP]
155+
> The bundling and minification of the JavaScript code is beyond the scope of this article.
156+
157+
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).
158+
159+
## See also
160+
161+
- [.NET Aspire dashboard configuration](configuration.md)
162+
- [Standalone .NET Aspire dashboard](standalone.md)
163+
- [Browser telemetry sample](https://github.com/dotnet/aspire/tree/main/playground/BrowserTelemetry)

‎docs/fundamentals/dashboard/overview.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
---
22
title: .NET Aspire dashboard overview
33
description: Overview of .NET Aspire dashboard and getting started.
4-
ms.date: 05/30/2024
4+
ms.date: 10/03/2024
55
ms.topic: reference
66
---
77

88
# .NET Aspire dashboard overview
99

10-
[.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.
10+
[.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.
1111

12-
## Using the dashboard with .NET Aspire projects
12+
## Use the dashboard with .NET Aspire projects
1313

1414
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.
1515

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net8.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
<IsAspireHost>true</IsAspireHost>
9+
<UserSecretsId>7247ba20-5e3e-4299-afa7-4ca58ebe3488</UserSecretsId>
10+
</PropertyGroup>
11+
12+
<ItemGroup>
13+
<PackageReference Include="Aspire.Hosting.AppHost" Version="8.2.0" />
14+
<ProjectReference Include="..\BrowserTelemetry.Web\BrowserTelemetry.Web.csproj" />
15+
</ItemGroup>
16+
17+
</Project>

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
var builder = DistributedApplication.CreateBuilder(args);
2+
3+
builder.AddProject<Projects.BrowserTelemetry_Web>("web")
4+
.WithExternalHttpEndpoints();
5+
6+
builder.Build().Run();

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"$schema": "http://json.schemastore.org/launchsettings.json",
3+
"profiles": {
4+
"https": {
5+
"commandName": "Project",
6+
"dotnetRunMessages": true,
7+
"launchBrowser": true,
8+
"applicationUrl": "https://localhost:15887;http://localhost:15888",
9+
"environmentVariables": {
10+
"ASPNETCORE_ENVIRONMENT": "Development",
11+
"DOTNET_ENVIRONMENT": "Development",
12+
"DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16175",
13+
"DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037",
14+
"DOTNET_ASPIRE_SHOW_DASHBOARD_RESOURCES": "true"
15+
}
16+
},
17+
"http": {
18+
"commandName": "Project",
19+
"dotnetRunMessages": true,
20+
"launchBrowser": true,
21+
"applicationUrl": "http://localhost:15888",
22+
"environmentVariables": {
23+
"ASPNETCORE_ENVIRONMENT": "Development",
24+
"DOTNET_ENVIRONMENT": "Development",
25+
"DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http://localhost:16175",
26+
"DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17037",
27+
"DOTNET_ASPIRE_SHOW_DASHBOARD_RESOURCES": "true",
28+
"ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
29+
}
30+
},
31+
"generate-manifest": {
32+
"commandName": "Project",
33+
"launchBrowser": true,
34+
"dotnetRunMessages": true,
35+
"commandLineArgs": "--publisher manifest --output-path aspire-manifest.json",
36+
"applicationUrl": "http://localhost:15888",
37+
"environmentVariables": {
38+
"ASPNETCORE_ENVIRONMENT": "Development",
39+
"DOTNET_ENVIRONMENT": "Development"
40+
}
41+
}
42+
}
43+
}

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning"
6+
}
7+
}
8+
}

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning",
6+
"Aspire.Hosting.Dcp": "Warning"
7+
}
8+
}
9+
}

‎docs/fundamentals/dashboard/snippets/BrowserTelemetry/BrowserTelemetry.ServiceDefaults/BrowserTelemetry.ServiceDefaults.csproj

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net8.0</TargetFramework>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<Nullable>enable</Nullable>
7+
<IsAspireSharedProject>true</IsAspireSharedProject>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<FrameworkReference Include="Microsoft.AspNetCore.App" />
12+
13+
<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="8.8.0" />
14+
<PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="8.2.0" />
15+
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
16+
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
17+
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
18+
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
19+
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.9.0" />
20+
</ItemGroup>
21+
22+
</Project>

0 commit comments

Comments
 (0)