Documentation about using Aspire dashboard with browser telemetry

[JamesNK]

See https://github.com/dotnet/aspire/issues/4917

• Documentation should discuss enabling OTLP HTTP endpoint
• Discuss CORS. Aspire should enable automatically but it should be mentioned that has happened so folks know they'll need to think about it if deploying their app with telemetry enabled
• Briefly discuss setting up OTEL in a browser app (should mostly point to existing OTEL docs)
• Link to sample app if available - https://github.com/dotnet/aspire-samples/issues/409

---

Associated WorkItem - 308083

[aaronpowell]

Let's time this with #1585

[JamesNK]

@IEvangelist Where would this content go?

Something to keep in mind that people could want to gather browser telemetry from an app that is integrated into an Aspire solution, in which case they need to enable the OTLP HTTP endpoint, like so: https://github.com/dotnet/aspire/blob/9a59d122949de428321599c503da59c54fb673d6/playground/BrowserTelemetry/BrowserTelemetry.AppHost/Properties/launchSettings.json#L12

Or they have the standalone dashboard, and want to collect browser telemetry. In that case they need to set configuration when launching the container to expose the OTLP port, and to enable CORS.

[aaronpowell]

With #1585 I'm intending that we cover how to use the browser OpenTelemetry npm packages to push to the Aspire dashboard (already have that sample ready).

For general configuration, I'd think that we want the content to land here: https://learn.microsoft.com/en-gb/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash

[JamesNK]

Ideally:

• A tutorial under the standalone mode TOC item would be good if we have one.
• Dashboard configuration at dashboard configuration
• App host configuration somewhere. I don't there is a doc page on app host configuration. One should be added. It should go under app host TOC item.

Issue for adding app host configuration page: https://github.com/dotnet/docs-aspire/issues/1602

[IEvangelist]

Ideally:

• A tutorial under the standalone mode TOC item would be good if we have one.
• Dashboard configuration at dashboard configuration
• App host configuration somewhere. I don't there is a doc page on app host configuration. One should be added. It should go under app host TOC item.

Issue for adding app host configuration page: #1602

Agree on all fronts, and I commented on #1602 - we have content for launch profiles already.

[JamesNK]

I don't feel this is done. How do I as an Aspire user know that I can configure Aspire to receive browser telemetry? Low level configuration is good to link to, but it isn't a good way for people to discover this capability.

Todo:

• [ ] Documentation that says you can do this
• [ ] Documentation about app host configuration

[IEvangelist]

I just realized that this was re-opened, sorry I didn't notice sooner @JamesNK. I need a bit of clarification on these asks.

Documentation about app host configuration

Isn't that what the CORS config section speaks too? If not, what am I missing. I looked through the linked PR in dotnet/aspire and didn't see anything that stood out.

As for this:

Documentation that says you can do this

I can add something in the overview, if you're good with that?

[JamesNK]

Documentation about app host configuration

Isn't that what the CORS config section speaks too? If not, what am I missing. I looked through the linked PR in dotnet/aspire and didn't see anything that stood out.

No. That doc is for configuring the dashboard. Configuration for the app host is different. It comes from setting env vars in launchSettings.json. Note that some settings in the app host flow through the dashboard which is why it could seem like there is one thing, but they are different.

I can add something in the overview, if you're good with that?

I think there should be a section at https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/telemetry that discusses collecting browser telemetry.

It would talk through configuring OTLP HTTP endpoint, CORS, reading info from env vars for sending to the right location.

[IEvangelist]

Awesome, thank you - that's the context I was missing.

[veldfolds]

i think i may need that section like now, please

[DGAISmith]

A quick question for clarity on my end (prior to the doc additions being proposed above). Is it accurate to say:

1. The CORS configuration section (oltp-cors) only applies when running the dashboard in standalone mode.
2. When running via AppHost, the Dashboard CORS configuration is populated automatically using the endpoints of each resource defined in the AppHost (added via this pull request - 5212).
3. Considering the two points above - if I have a node app which is internally configured to use a custom domain (www.my-fancy-app.co.uk, manually added to hosts file and self-signed cert added locally) - I'm unable to use CORS config in point 1 when running the AppHost, and because Aspire will use localhost:[RandomPort] when starting the npm app up (and no way to ask AppHost to use a custom domain), I will always get a CORS error when the npm app attempts to transmit telemetry to the dashboard otlp endpoint?

In short - is there a way to wildcard CORS for the dashboard when running via AppHost?

[IEvangelist]

That's a good question for @JamesNK