[docs] Add getting started docs showing how to set up OTLP exporter with Aspire dashboard

[CodeBlanch]

Changes

• Add getting started docs which show how to use the OtlpExporter with Aspire dashboard

Merge requirement checklist

• [X] CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 86.39%. Comparing base (6250307) to head (17d5785). Report is 290 commits behind head on main.

Additional details and impacted files

[](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) ```diff @@ Coverage Diff @@ ## main #5779 +/- ## ========================================== + Coverage 83.38% 86.39% +3.00% ========================================== Files 297 256 -41 Lines 12531 11140 -1391 ========================================== - Hits 10449 9624 -825 + Misses 2082 1516 -566 ``` | [Flag](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `?` | | | [unittests-Project-Experimental](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `86.21% <ø> (?)` | | | [unittests-Project-Stable](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `86.21% <ø> (?)` | | | [unittests-Solution](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `86.38% <ø> (?)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry#carryforward-flags-in-the-pull-request-comment) to find out more. [see 207 files with indirect coverage changes](https://app.codecov.io/gh/open-telemetry/opentelemetry-dotnet/pull/5779/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry)

[samsp-msft]

I put a comment inline, but want to re-iterate here, why not use the Aspire template as the starting point. Its has everything already done and working.

The 90% scenario is probably not adding your own Activities and Metrics, but we can walk them through that as stage 2.

[martinjt]

I'm not sure why we're putting docs here, where's the request coming from? The Docs need to live in open-telemetry/docs, these examples are legacy ones. If this is something we think is valuable then it should be debated in an OpenTelemetry docs PR.

I also don't think we should be talking about Aspire here. Aspire has it's own docs on the Microsoft site. We definitely shouldn't be changing the template to use the Aspire one, that's the beyond the scope of the OpenTelemetry project.

[noahfalk]

I also don't think we should be talking about Aspire here

I didn't think the intent was to be a doc on how to use Aspire. I believe @CodeBlanch chose the dashboard because its a free + OSS viewer for OTLP data that is trivial to set up. The dashboard is a standalone tool that can run completely independently of Aspire and consume some arbitrary OTLP telemetry. For example here is a python telemetry demo that felt the dashboard was a good choice https://tonybaloney.github.io/posts/using-dotnet-aspire-dashboard-for-python-opentelemetry.html.

[martinjt]

Thanks @noahfalk, I'm fully aware of the dashboard and it's capabilities, I do advocate for it. This just isn't the place to promote it.

Like I said, these examples are legacy, and need to be all moved into the main docs. If there's a tool that people should be using, it should be flagged across all the languages not just .NET and that's a much wider discussion that should be raised in the docs project.

[cijothomas]

I put a comment inline, but want to re-iterate here, why not use the Aspire template as the starting point. Its has everything already done and working.

This is just meant to show OpenTelemetry usage, and nothing more.

edit: +1 to below.

We definitely shouldn't be changing the template to use the Aspire one, that's the beyond the scope of the OpenTelemetry project.

[martinjt]

I think we need answers to the following questions:

1. Where is the request coming from to add this content? and why is there a need for it?
2. Why is this example in the .NET OpenTelemetry repo and not the Microsoft Aspire site?
3. Why is this in the repo, and not on the docs site?
4. Why should OpenTelemetry be promoting a thirdparty, non-CNCF tool?

I know what the Microsoft Aspire dashboard is, and why it's useful, but this isn't something that OpenTelemetry has adopted. If this is something we're doing now, we should look at adding examples of the signoz, qryn, grafana stacks too, but that's then a very slippery slope.

There is an ongoing discussion about a local visualisation tool, and until that's resolved, I don't think this should be part of the official repo.

[CodeBlanch]

I think we need answers to the following questions:

1. Where is the request coming from to add this content? and why is there a need for it?
2. Why is this example in the .NET OpenTelemetry repo and not the Microsoft Aspire site?
3. Why is this in the repo, and not on the docs site?
4. Why should OpenTelemetry be promoting a thirdparty, non-CNCF tool?

I know what the Microsoft Aspire dashboard is, and why it's useful, but this isn't something that OpenTelemetry has adopted. If this is something we're doing now, we should look at adding examples of the signoz, qryn, grafana stacks too, but that's then a very slippery slope.

There is an ongoing discussion about a local visualisation tool, and until that's resolved, I don't think this should be part of the official repo.

Here are my replies..

1. Where is the request coming from to add this content? and why is there a need for it?

No one asked for it 🤣 I needed to test OTLP transmission for some code I was working on. I tried the Aspire dashboard standalone container and it worked great. We have one-off guides. A Jaeger one. A Prometheus+Grafana one. Nothing for logs, I don't think. I thought it would be great to show all signals together using OTLP and Aspire made it really easy to do that.

2. Why is this example in the .NET OpenTelemetry repo and not the Microsoft Aspire site?

This isn't an Aspire thing. This is an OTLP thing. Just happens to use Aspire for the visualization. Happy to swap out Aspire if there is something that works equally well with relative ease.

3. Why is this in the repo, and not on the docs site?

No real reason other than I just took the existing getting started docs in the repo and modified them for OTLP. Status quo more or less.

4. Why should OpenTelemetry be promoting a thirdparty, non-CNCF tool?

It certainly wasn't the intention to promote Aspire. The goal is to promote OTLP! What I wanted to show was how easy it is (few lines of code) to enable all signals with OTLP export. Also how easy it is for users to send them wherever they want. Having the visualization is just a nice-to-have for new users to immediately see the fruits of their labor and get excited about OpenTelemetry.

If this is something we're doing now, we should look at adding examples of the signoz, qryn, grafana stacks too, but that's then a very slippery slope.

We do promote other OSS stacks though. The only thing we didn't promote was OTLP which is really the de facto way to do OpenTelemetry in my mind. The goal with this guide is for us to say to users OTLP is what you should be doing, not the other stuff 😄

[samsp-msft]

4. Why should OpenTelemetry be promoting a thirdparty, non-CNCF tool?

It certainly wasn't the intention to promote Aspire. The goal is to promote OTLP! What I wanted to show was how easy it is (few lines of code) to enable all signals with OTLP export. Also how easy it is for users to send them wherever they want. Having the visualization is just a nice-to-have for new users to immediately see the fruits of their labor and get excited about OpenTelemetry.

As somebody who bridges between Aspire and OTel, I don't see how this is promoting Aspire, it's using the standalone dashboard to provide a quick and easy way to view OTLP data. I have written docs on how to send telemetry to Prometheus/Grafana/Yeager. The steps required to configure all of them dwarf the topics of how to setup telemetry - the standalone dashboard illustrates that concept with one call to docker, and one line setting up the OTLP exporter in the app. There is no use of Aspire libraries or other changes to the project that would tie the projects to Aspire.

The work we are doing in Aspire is to make using OpenTelemetry easy. There is nothing proprietary in Aspire when it comes to telemetry - its providing (hopefully) good defaults for setting up and configuring OTel in your projects. We include the OTLP exporter, both to drive the dashboard and because we see it as setting up the apps for the long term for telemetry. Aspire is not tied to Microsoft/Azure backends.

[martinjt]

I've discussed this with a lot of people, and the general consensus is that unless this is something that would be accepted by docs, it shouldn't be merged here. This repo isn't the place for documentation or guides, that's been debated a lot and the docs team have been clear that docs is the place for this.

If there is an example application, that details how to run the example, that's different, but this is clearly a guide, with narrative on how and when to use it. This is evidenced by the title, and the code in the readme in telling people how to recreate it in code.

My suggestion is to look at how this could be formatted into something that could go into the main docs site, or as a blog for the OpenTelemetry blog. However, it's not something that should live in this repo. If people believe that Aspire is truly useful and the one solution here, you shouldn't have a problem justifying that with the docs team as the solution they use for all languages.

If we wanted to make this in-keeping with the other example solutions, all the narrative should be removed from the readme and instead it should say how to run the solution only.

[cartermp]

Speaking on behalf of the docs side of things, I wouldn't say no to an Aspire-related "get started" or some other document on the website, especially if we expect many .NET developers who learning OTel and Observability to use Aspire. I don't view it as terribly different from ASP.NET Core in that regard.

[cijothomas]

Speaking on behalf of the docs side of things, I wouldn't say no to an Aspire-related "get started" or some other document on the website, especially if we expect many .NET developers who learning OTel and Observability to use Aspire. I don't view it as terribly different from ASP.NET Core in that regard.

Just to be clear, Aspire (the use case shown here) has nothing to do with .NET. Its just used as a tool to view all 3 signals with a one line exe/docker. If there is another tool blessed by spec/docs, we should use that. If there is none today, the SIG can chose aspire, and once spec/doc recommends a particular tool, this should be replaced with the recommendation.

[martinjt]

@cijothomas that doesn't change fact that this doesn't live in this repo though. As I said you should take that to the docs team as a PR, and it should be removed from here.

On "it has nothing to do with .NET", I think that's a little disingenuous. It's written by the team who works on .NET, written in .NET, and has primarily targeted .NET developers for the last 12 months and only recently has it branched out to other languages since the dashboard has been launched as a separate thing. It has a lot to do with .NET. I agree that the dashboard can (and has) been used outside of pure .NET solutions, but to say it has nothing to do with .NET is not accurate.

[mtwo]

Following up from the SIG call and from discussions with the GC and @svrnm (should have also discussed with you @cartermp, apologies): there's a longstanding desire to add getting started guides to the opentelemetry.io website, and this would be a great example of this. Aspire is OSS and permissively licensed, so it's a great fit for this.

I've messaged @svrnm, and he or one of the other docs contributors will likely reach out to help move this over if we're all agreed.

@cijothomas I didn't catch you at the SIG, but I know that you're active in the comments. Are you okay with this plan?