Reorganize spring boot starter page about opentelemetry.io HOT 19 CLOSED

Thank you for your explanations @svrnm.

The following structure that you propose could make sense to me:

Automatic
`- Java agent
`- Spring Boot Starter

The differences between the Java agent and the Spring Boot stater could then be moved to the Automatic entry.

Spring Boot is very popular in the Java ecosystem. In term of documentation discovery, it may make more sense to keep the current Spring Boot page and place it below Java :

Java
`- Getting Started
`- Spring Boot
`- Instrumentation
`- Automatic

Automatic would then only be related to the Java agent.

Something seems important to have in mind to re-organize the "Automatic" content. The Spring Boot Starter is "semi-automatic instrumentation", as we have tried to explain in the documentation:

The Spring Boot Starter will probably never have as many automatic instrumentations as the Java agent (technically the Java agent uses byte code instrumentation to instrument the code and the Spring Boot Starter tries to wrap accessible code).

from opentelemetry.io.

Yeah, that's another case of "Automatic Instrumentation" creating confusion unfortunately :-(

we might be able to compromise on "Out of the box" for now?

from opentelemetry.io.

@svrnm can you suggest which structure would fit into the overall organization of the website?

from opentelemetry.io.

@jeanbisutti FYI

from opentelemetry.io.

I think it'd fit under Libraries:

https://opentelemetry.io/docs/languages/java/libraries/

I think there's an open issue to automate the list of instrumentation in the docs, BTW?

from opentelemetry.io.

can you suggest which structure would fit into the overall organization of the website?

I am not 100% sure what the best place is, because we do not have a comparable case, the closest wie have is /docs/languages/net/netframework/. So based on that an argument could be made that we have it under "Language APIs & SDKs > Java > Spring Boot" or what @theletterf said:

I think it'd fit under Libraries:

This would be kind of fitting (not perfect) since this page speaks about instrumenting your dependencies (libraries, frameworks, here spring boot) and getting either out of the box experience or something like the starter which adds that capability additionally.

from opentelemetry.io.

it doesn't feel right to have "Spring Boot" under "Automatic"

Both the OpenTelemetry Java agent and the Spring Boot starter provide automatic instrumentation. So, I don't follow.

from opentelemetry.io.

@svrnm can you help?

from opentelemetry.io.

Apologies, for not providing any reasoning on why I felt that way. To be honest, I needed to wrap my head around it because it really was just a "feeling", but I think I can put it in words now:

The "Automatic" page currently focuses on the Java agent which is as you stated a different solution as the Spring Boot Starter. This means the Spring Boot Starter is hidden away within the agent documentation and by that might be hard to find fore people. Using the current structure the following would be the right way of doing it (imho):

Automatic
`- Java agent
`- Spring Boot Starter

This is of course a major change in our Information Architecture and it also gets more complicated due to this discussion, where we consider moving "Automatic" out of that place in it's own space.

@open-telemetry/docs-maintainers WDYT?

from opentelemetry.io.

@jeanbisutti just a quick update that I didn't forget about this discussion, I just couldn't find the time to think about it properly yet, will follow up with you eventually!

from opentelemetry.io.

@svrnm, FYI @zeitlinger wanted to discuss this topic during the next OTel doc SIG meeting. I am not sure to be able to attend this meeting because I will be off.

from opentelemetry.io.

That's a good idea, thanks for the headsup!

from opentelemetry.io.

Hi @svrnm and @theletterf

I have discussed with @zeitlinger. The Zero-code Instrumentation menu entry is great!

To split the Spring Boot page, what do you think about the following structure?

Zero-code instrumentation
- Java
  - Agent
  - Spring Boot => How to instrument Spring Boot with OpenTelemetry (Java agent VS Spring Boot starter)
  - Spring Boot starter 
     - Getting started => dependency management  + overview table of automatic instrumentations
     - SDK configuration
     - Automatic instrumentation
     - Annotations

from opentelemetry.io.

Hey @zeitlinger,

agreed, having this re-organized was urgently needed. On your structure question: I do not like the idea of having Spring Boot and Spring Boot Starter split that way. I understand where you are coming from and what problem you are trying to solve, but for an end user this is going to be more confusing than helpful (they come with zero context and are presented with those 2 entries, so they may assume very different things from there). Two options I see are the following:

- Java
  - Agent
  - Spring Boot Starter
     - Agent vs Starter
     - Getting Started
     - SDK configuration
     - Instrumentation libraries
     - Annotatons

or

- Java
  - Agent
  - Spring Boot
     - Agent vs Starter
     - Starter
       - SDK configuration
       - Instrumentation libraries
       - Annotatons

I prefer the first option.

Note, that you should use "Instrumentation Libraries" and not "Automatic Instrumentation" which is a misleading term

from opentelemetry.io.

thanks a lot - sounds good

from opentelemetry.io.

I also prefer the first option.

Note, that you should use "Instrumentation Libraries" and not "Automatic Instrumentation" which is a misleading term

This page would not be about the instrumentation libraries but about the instrumentations available just by adding the starter dependency: https://deploy-preview-4528--opentelemetry.netlify.app/docs/zero-code/java/spring-boot/#automatic-instrumentation

@svrnm What naming would you suggest?

from opentelemetry.io.

Getting the naming right isn't easy.😅

"Out of the box" seems great.

Thank you for the feedback and the suggestion!

from opentelemetry.io.

Getting the naming right isn't easy.😅

Yes, we have some terminology glitches in OpenTelemetry that we need to address eventually...

from opentelemetry.io.

@svrnm @zeitlinger I have created a PR for the new organization: #4554 The documentation is much better

from opentelemetry.io.