Prometheus client compatibility guide page

[jack-berg]

• I have read and followed the Contributing docs, especially the "First-time contributing?" section.
• This PR has content that I did not fully write myself.
  • I used AI and I have read and followed the Generative AI Contribution Policy.
• I have the experience and knowledge necessary to understand, review, and validate all content in this PR.¹

---

Solves open-telemetry/opentelemetry-specification#4875.

Proposal to add a new page at location "Docs -> Compatibility -> Prometheus Clients".

The point of this document is to act as a resource for users familiar with prometheus client APIs and concepts, and explain how those APIs / concepts map to opentelemetry.

Its a combination of prose describing conceptual differences, and code snippets showing how to achieve key API usage patterns in both prometheus and opentelemetry, and in a variety of languages.

PRs for referenced code excerpts:

• opentelemetry-java-examples: ttps://github.com/Prometheus compatibility opentelemetry-java-examples#1032
• opentelemetry-go-contrib: Add snippets for prometheus clients compatibility documentation opentelemetry-go-contrib#8715

I'm less confident in the go examples, but thought it was important to include to show the vision for the page. That is, I envision the page demonstrating these key API usage patterns in a variety of languages which have popular prometheus client libraries.

Also, the go examples are going to be dependent on resolving #5374, so that we can have a proper home for these snippets with compile validation.

See Page Preview

cc @open-telemetry/prometheus-interoperability

Footnotes

1. Yes, I can answer maintainer questions about the content of this PR, without using AI. ↩

[chalin]

Nice work.

A comment about the content organization. Let me first make a proposal about a possible logical organization and we can discuss how to implement it later -- if you like the proposed logical organization.

As a logical organization, what if we had:

• An index file with the content of the conceptual differences section
• Then subsection pages per language. In these pages the tabbed panes would be for OTel vs Prometheus

It feels like that would offer a good experience for readers who might want to focus on one language or at least one at a time.

WDYT @jack-berg?

[jack-berg]

That's definitely an option!

One observation I made developing this page that I was surprised by: if I click the "Go" or "Java" tab of a particular tabpane, all the other tabpanes on the page update together. It was unintuitive at first, but I grew to like it because as you note, a typical use would want to consume all the java content, or all the go content. It would be unusual to want to consume a combination of both at the same time.

One benefit of keeping the content all on one page is that it forces a degree of uniformity in the set of examples that are discussed and how they are presented. I didn't was to build an exhaustive guide and found that focusing on the concepts / flows that all or most clients helped resist going down the rabbit hole of too much detail.

Of course, there are likely techniques that we could leverage to achieve uniformity which don't display everything all on one page.

Ultimately I'm happy to defer the docs maintainers on info architecture questions like this.

[chalin]

@jack-berg - which content-module update are essential to this PR? Go and Java I presume?

The build is failing which versions of those do you want exactly?

[jack-berg]

@jack-berg - if I can resolve the link issues and adjust to the tools folder going away, are you ok if I just push a commit to this PR?

Yes you can push to the branch. But links is failing because I checked in the changed to the submodules for demonstration purposes. To fix, I need to merge the corresponding PRs to go / java, and update the submodules to point to the latest refs. Now that @tiffany76 has approved, I've requested the opentelemetry-go-contrib PR be merged, and have merged the opentelemetry-java-examples PR.

[jack-berg]

@chalin dependent PRs in opentelemetry-go-contrib, opentelemetry-java-examples are merged, .gitmodules updated to point to latest refs, and cleaned up.

I think this is ready for a final look.

[chalin]

LGTM. Thanks for this! 🙌🏻