Visualizations we support in the documentation

[svrnm]

This is a follow up to open-telemetry/opentelemetry-dotnet#5779, but we had similar discussions in the past, so I am trying to capture this here, to allow us to make a decision and eventually write it down in our contribution guidelines.

As of today, we restrict the documentation to demonstrate backend ingest only via the OpenTelemetry Collector or console output. This means we do not show visualizations of any kind.

The main reason for that is, that we wanted to stay neutral towards the many backends¹ that are available to end users: even if we restrict ourselves to open source offerings, there are ~20 potential candidates to choose from. So if we choose one (or some of them), we open up the question why not having others as well, which either leads to breaking the neutrality or a maintenance overhead by supporting all of them.

The purpose of this discussion is to move towards an answer for this question, what visualizations do we support in the documentation? Is the current solution replaceable with something better?

Edit, to clarify, a different way to ask the question is: if we accept aspire dashboard, and someone provides us with a PR with , why would we decline/accept them?

Footnotes

1. not listed there are Aspire, OTel Desktop Viewer, OTel TUI, TraceLens, tails and some other ones available out there. ↩

[theletterf]

In an ideal world, we'd have a very basic visualization backend which could be run locally and be available for debugging or educational purposes, like some sort of otel-graph that's not meant to compete with any existing backend solution.

I wonder if a project like this has ever been discussed.

[svrnm]

There was/is an ongoing discussion about that: open-telemetry/oteps#230

[cartermp]

FWIW I’d prefer we allow .NET to use Aspire, just as if another tool had a community-preferred dev-time OSS backend to use too. Aspire is interesting, it’s both an app framework and backend viz tool, and it’s what the .NET community is starting to coalesce around for cloud-native applications. We should lean into that, especially if folks on the .NET SIG have motivation to maintain it

[svrnm]

🤔 -- so, the line you would be drawing is that the visualization used in a SIG's documentation is, it is a "community-preferred dev-time OSS backend"? So, if it would not be .NET how would we determine that? I just want to make sure that if we do that, we can explain why other viz tools might or might not get their spot in the documentation.

[austinlparker]

IMO this is more akin to something like Spring in the Java world -- it's less a 'visualization tool' and more of a service framework. I'd also compare it to something like next.js. In that sense, I think it's fine to create subsections that highlight how these frameworks are integrating with OpenTelemetry. It would make sense to put them alongside the language in the docs, IMO.

[cijothomas]

+1. The Aspire we are talking about is the DashBoard only, nothing more.

[austinlparker]

+1. The Aspire we are talking about is the DashBoard only, nothing more.

But you can't use the dashboard independently of the rest of the framework, right?

[cijothomas]

You can.! (the PR just showed that!)
Infact it can be used by any OTel language (if they chose to!)

[austinlparker]

You can.! (the PR just showed that!) Infact it can be used by any OTel language (if they chose to!)

Ah, ok. Sorry, it was unclear to me. Well, I think it's still fine in the sense that its permissively licensed and open source.

[samsp-msft]

We probably need a better name for it - the standalone Aspire dashboard is a docker container that exposes an OTLP endpoint and it then shows whatever logs/traces/metrics were sent to it in a browser-based UI. https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash It doesn't care what language/sdk was generating the telemetry. As long as you have docker, you can run it.

https://github.com/ymtdzzz/otel-tui?tab=readme-ov-file does something similar with a console-based UI.

I would suggest:

• Enable docs to use the tool of their choice that makes most sense for the language/sdk the docs are targeting, but...
• Have a page(s) in the OTel docs for local telemetry viewers, showing how to setup and use each of them. There would be pages for Aspire, otel-tui, the otel-collector visualizer etc. Ideally each page would follow a similar pattern so you can easily compare them to choose the best one for you.
• Have a standard blurb that can be included in the docs such as "this example uses otel-tui to visualize the telemetry locally. Other local visualizers are available, see for more details on how to use them"

That way the docs don't become overly long winded showing each alternative example, or need to be updated as new ones are available.

I am biased as I work on the Aspire one, so naturally gravitate towards it, but if all I was trying to diagnose a remote service, and all I had was a ssh prompt, being able to quickly use otel-tui to see what is going on would be invaluable

[mtwo]

I'm generally fine with us supporting getting started guides for backends that are both OSS and permissively licensed. Jaeger, Zipkin, Prometheus (without Grafana), Aspire, etc. would qualify. Splunk, Datadog, Grafana, Elastic, etc. would not.

That being said, building and continually maintaining these guides is a lot of work and I don't think that it's a requirement that we provide these. Given the amount of work, and that Jaeger, Zipkin, Prometheus, and others already have good guides hosted elsewhere, it may make sense for us to just provide guides for lightweight visualization tools like our own z pages, frameworks like Aspire and Spring, and OTel-specific debugging tools that show data from a single agent or Collector.

I'm not super opinionated about this, happy to defer to others.

[svrnm]

That being said, building and continually maintaining these guides is a lot of work and I don't think that it's a requirement that we provide these. Given the amount of work [...]

This is the thing I am most worried about, but at the same time it's potentially part of the solution. Ultimately, for everything outside "core" it boils down to "you contribute it, you maintain it", similar to what many other SIGs do for their -contrib repos. We have component owners in place now, so we can assign parts of the docs to individuals, and it's then their responsibility to keep that code up-to-date.

Quoting @theletterf:

We need a couple of things before we start:

• Some kind of demarcation rules for what goes where
• An advisory note that we'd promote content from contrib to core if we see fit?

Of course this still comes with some maintenance overhead for docs maintainers&approvers, so we need to make a deliberate choice if this is what we want to do.

[theletterf]

I think this would work well!

[cijothomas]

I'm generally fine with us supporting getting started guides for backends that are both OSS and permissively licensed. Jaeger, Zipkin, Prometheus (without Grafana), Aspire, etc. would qualify.

@mtwo Can you elaborate on without Grafana part? We liberally showcase Grafana UI in OTel .NET repo, OTel Demos etc. Is that discouraged?

[mtwo]

Yikes, you're right, thanks for pointing that out! I don't really have a good answer, I'll defer to yourself, Severin, and others.

[samsp-msft]

Grafana has both commercial and OSS variants (AGPL).

[austinlparker]

To the original point/question here, I'd ask why not use the registry (or create some sort of registry-like 'integrations' page) to highlight this sort of thing?

[samsp-msft]

Makes sense. Ideally it needs a category/section that can be deep linked into to enumerate the local viewers. There doesnt seem to be an appropriate category in the current registry for this kind of tool.

[svrnm]

Not sure if I understand how that should work?

[svrnm]

Please see #4475 (reply in thread)