Add Quarkus documentation

[brunobat]

This PR adds documentation on how to use the zero-code OpenTelemetry instrumentation with the Quarkus java runtime.

[brunobat]

CC @trask @jeanbisutti

[chalin]

Hi. The build is failing, see the following log for details: https://app.netlify.com/sites/opentelemetry/deploys/679caf7a75f6fc0008075aa4. See inline suggestions for a possible fix.

[jeanbisutti]

Thank you @brunobat!

[chalin]

A partial copyedit pass.

[svrnm]

Hey @brunobat, thanks for raising this issue! We talked about this (and Deno) last Monday during the SIG communcations call, since both set precedence for having documentation for external projects. Overall we are excited for other projects to take on the instrumentation directly, but we need to make sure we provide some guidance here (when do we accept such a page and when do we decline, etc.), please give us some more time to evaluate.

cc @open-telemetry/docs-approvers @jack-berg

[brunobat]

@svrnm do you need me in the next communications meeting?

[trask]

I strongly support 💪

@brunobat and the Quarkus team have been active members of the OpenTelemetry Java community for a long time, and Quarkus represents an important alternative to the Spring ecosystem for our users

let me know if I can help further, thanks!

[chalin]

Thanks for commenting already @svrnm. Let me share some of what I recall from our discussion during the last Comms meeting.

Actually, first let's consider that we already have:

• Registry entries already: https://opentelemetry.io/ecosystem/registry/?s=quarkus
• The main entry has a link to https://quarkus.io/guides/opentelemetry

The main question I have is What added value is there for the content of this PR vs. the Quarkus docs referenced above? Is there anything new and exclusive here? If so, why isn't it a part of the Quarkus docs? If it is just a repetition, then it introduces a maintenance overhead.

Some repetition can be ok in a blog post, so maybe that is what is needed here?

As @svrnm mentioned, we're trying to find a solution that we can apply uniformly.

My 2 cents. Open to further discussion.

cc @svrnm @tiffany76 @jack-berg

[jeanbisutti]

The OpenTelemetry instrumentation developed on the Quarkus side covers one important use case in the Java world not possible with the OpenTelemetry Java agent today: instrument a Quarkus GraalVM native application with OpenTelemetry. This use case was an important reason to make the OTel starter stable.

From my side, it would make sense to highlight this in a very visible way for the OpenTelemetry users (with a new page for example).

There are also other scenarios exposed on the OpenTelemetry starter page for which the OpenTelemetry instrumentation developed on the Quarkus side is an alternative to the OpenTelemetry Java agent:

cc @chalin @svrnm @tiffany76 @jack-berg @trask @brunobat

[brunobat]

@svrnm I think this shouldn't be about what the PR adds in terms of documentation completeness but:

1. A recognition that the Quarkus team has done extensive OpenTelemetry instrumentation of their framework
2. Provide another option to the users when they search about zero code instrumentation in Java.
3. Do we want the OpenTelemetry documentation to ignore all the OpenTelemetry work done outside of the OpenTelemetry project?

[maxandersen]

"The main question I have is What added value is there for the content of this PR vs. the Quarkus docs referenced above"

mainly visibility to those looking into using OpenTelemetry standards sees that there a ways beyond just the opentelemetry github org provided libraries that enable great support for OpenTelemetry in Java ecosystem.

I definitely grok how it would be relevant to clearly mark that the Quarkus effort is from "outside" the github org/opentelemetry. Would that help to be called out more explicitly ?

[jack-berg]

I love the direction quarkus has taken and hope other libraries and frameworks will follow suit!

But projecting to that future, what's the scope of opentelemetry.io? We definitely want to have great discoverability of instrumentation / integrations that live both inside and outside of the opentelemetry github org. Currently, we have a page called "Instrumentation ecosystem", with a section called Native instrumentation, which lists the libraries which support native instrumentation. The list is driven by entries in the registry.

Quarkus is on that list. I think the important questions to ask are:

1. Is a link always enough? Should we "feature" / "highlight" specific instrumentations / integrations which are particularly important? If yes, what's the heuristic? How do we avoid favoritism?
2. If we want to say more on opentelemetry.io than just linking, can we accommodate that with the registry? Could a registry entry contain markdown which is rendered when we build the list of native instrumentations?

[svrnm]

Let me say this as well: I am a big fan of Quarkus providing native opentelemetry support. It is in line with the mission and vision of our project, and helps us a ton. So we need to distinguish two things here:

1. The recognition that quarkus is a first class early adopter of this idea of providing native instrumentation through OpenTelemetry.
2. How projects like quarkus and others (e.g. deno, cc @lucacasonato) can get their appropriate space in our documentation.

For (1) adding a page for quarkus is one of many options, but as you can see not the easiest one. Much easier, are the following:

• Having a blog post about quarkus & OpenTelemetry (which includes some social media posting), maybe even on both project pages?
• Feature & highlight those projects on https://opentelemetry.io/ecosystem/integrations/ and https://opentelemetry.io/ecosystem/registry/
• ...

Especially the blog post is only a matter of "write it, publish it" and we have previous examples of that, e.g. https://opentelemetry.io/blog/2024/new-otel-features-envoy-istio/

I am happy to help with that!

For (2) this is not a discussion about quarkus, but a generalized thing we need to resolve. So nothing we say or write in that context that may feel like a push back means that we do not recognize and appreciate the work. It also does not say that we will not find a way to have these projects promoted properly. And, even if we may decide to not merge this PR, this also not a devaluation of your contribution @brunobat, quite the opposite: this discussion is highly valuable and important to have, so thank you for engaging in it with us.

What we need to do, is to answer the questions @chalin and @jack-berg posted, so let me pick them up to drive that discussion.

The main question I have is What added value is there for the content of this PR vs. the Quarkus docs referenced above

As @maxandersen the main difference is visibility: the registry and ecosystem pages are not at a prime spot, and if someone searches in the java documentation, they will only find them in the "Native Instrumentation" section, which already requires some contextual knowledge. So, I understand the driver behind this PR, but I also think that we should avoid duplicating docs that belong on the Quarkus website.

Is a link always enough? Should we "feature" / "highlight" specific instrumentations / integrations which are particularly important? If yes, what's the heuristic? How do we avoid favoritism?

Based on the discussions so far he answer to the question if a link is always enough is "no", but it's a starting point. I agree that it is not optimal for searchability and discoverability for endusers, so we need to think how we can do better here. And yes we need to find rules and guidelines what is promoted in which way. While quarkus and deno are a clear "yes", there are other less popular languages and frameworks, that might not hit the mark.

If we want to say more on opentelemetry.io than just linking, can we accommodate that with the registry? Could a registry entry contain markdown which is rendered when we build the list of native instrumentations?

Once again, the registry needs a major rehaul. It does a good job and has plenty of visitors these days, but it's still a project that would need much more love and attention.

To summarize, let's do the following:

• pick some low hanging fruits (blog post, etc.) to promote & appreciate quarkus implementation of OpenTelemetry
• find a broader solution for the generalized problem. Happy to chat about that at our next SIG call (Feb, 17th 10PST, 7CET)

[brunobat]

The registry is an interesting tool, but, take a look at the documentation and supported libraries in Quarkus and compare it with what's shown here:

We are an open source project with many thousands of lines of code dedicated to OpenTelemetry, in many different libraries and being a rectangle among other 866 entries does not match the effort we took.

Also, when searching on the website for zero code instrumentation you will find 2 entries, one for the OpenTelemetry agent and another for one of our competitors. What that tells you about favouritism?

I think the OpenTelemetry project should protect itself against external references from its website... Some lib might go rogue.
What about creating a banner or some warning on the top saying this piece of documentation is maintained by the Quarkus team, please use their support channels "here" for any questions?

[svrnm]

The registry is an interesting tool, but, take a look at the documentation and supported libraries in Quarkus and compare it with what's shown here:
We are an open source project with many thousands of lines of code in many different libraries and being a rectangle among other 866 entries does not match the effort we took.

I agree with that. As said, the registry is not the place it should be and it does also not yet give us a way to properly promote the projects that have OpenTelemetry integration. We had many discussions on how to make it better and we have many many outstanding issues on making it better, but at the end someone (2+ people) need to sit down and do the work for it, and so far nobody showed up or shifted their priorities towards that.

Also, when searching on the website for zero code instrumentation you will find 2 entries, one for the OpenTelemetry agent and another for one of our competitors. What that tells you about favouritism?

can you be more specific what you mean by "one of our competitors"? Is this around spring? If yes, we have it in the documentation because we have a group of people (@zeitlinger, @jeanbisutti and others) who maintain this work within the OpenTelemetry project. Interestingly the spring boot starter is itself competing with springs own solution (micrometer) which itself is also currently listed in the same way quarkus is listed.

You can ask a similar question around many programming languages that compete with the ones we list, vs the ones we do not (deno, zig, haskell, perl, etc.): they have a SIG and project within OpenTelemetry, so they are part of the official documentation.

And this is what all this discussion is about:

how can we embrace the kind of work you are doing alongside the work that is happening within the community?

I think the OpenTelemetry project should protect itself against external references from its website... Some lib might go rogue. What about creating a banner or some warning on the top saying this piece of documentation is maintained by the Quarkus team, please use their support channels "here" for any questions?

Yes, something like this can be part of the solution, we had a related discussion on that here: #4475

In my mind there are a few building blocks to move forward with this:

• We sit down together and write a blog post about Quarkus & OpenTelemetry and promote the work you are doing
• We need to rework some parts of the registry to make it easier and better for projects who care to turn their entry from "a rectangle among others" to something that stands out
• We find a better way to promote projects that are in line with OpenTelemetry's vision and mission within our website and documentation. Having a page like this one is one option, but there are many more, and I'd like to do some thinking and brainstorming on them before settling with something.
• We need to come up with guidelines when and how a project will be positioned and promoted in which degree. While the registry is a place for everyone (including non-oss), other places require a higher bar ("is it open source?", "is it a first class implementation?" "is it a native implementation?" "how popular is the project?" "are OpenTelemetry and the project 'friends' or is there any potential conflict between the two?", etc.

[jeanbisutti]

Some comments seem to suggest that was developed on Quarkus's side is just an OTEL-native instrumentation of a library

What was done on the Quarkus side is more than that.

Quarkus also seamlessly instantiates the OpenTelemetry SDK and supports OTel properties to change the configuration.

The OTel Spring starter is doing the same thing globally that is done on Quarkus side: seamlessly instantiating the OpenTelemetry SDK and providing out-of-the-box (native) OTel instrumentation.

In addition, Spring Boot and Quarkus are the two major microservice frameworks in the Java ecosystem.

The Spring Boot starter documentation is highly discoverable on the OTel website.

It is referenced just below the OTel agent in the left menu

In addition, documentation pages for the OTel Spring starter make this content more discoverable and visible to search engines.

So, why not also make it very visible on the OTel website that the Quarkus observability features are based on OTel?

[jeanbisutti]

About the risk of duplicating the documentation on the OTel and Quarkus sides

It does not make sense to duplicate the documentation.

The documentation of this PR is short and provides some guidelines for Quarkus with links to the Quarkus OTel documentation:

• https://quarkus.io/guides/opentelemetry

• https://quarkus.io/guides/opentelemetry-tracing

• https://quarkus.io/guides/opentelemetry-metrics

• https://quarkus.io/guides/opentelemetry-logging

The OTel Java agent is not the magic solution for every user scenario.

As a user, I would like the documentation published on the OTel website to provide me with some guidelines to help me choose which OTel solution to use to observe my application (see #6138 (comment)).

[svrnm]

So, why not also make it very visible on the OTel website that the Quarkus observability features are based on OTel?

I think there is a misunderstanding: I agree that we want to provide quarkus (and others) more visibility, this is less a question about the what and why, which are both clear. It's about the how. All I ask for is that we take the appropriate amount of time to discuss, plan and execute on that.

And, again, as a short term measure, let's start with a blog post! It has a lot of immediate reach!

[trask]

I'll join the next docs SIG meeting to discuss.

I'm happy to own the Quarkus documentation page under the Java SIG. It has been developed by one of our SIG members (@brunobat), with collaboration from one of our SIG approvers (@jeanbisutti), and I think it's good for our users to see that it's supported equally well as the Spring ecosystem.