opentelemetry.io
opentelemetry.io copied to clipboard
open-telemetry
Is it OpenTelemetry Java Agent or OpenTelemetry Javaagent?
"Java Agent" is the established term in the Java community, but I have seen many people outside of the Java community confused by this, b/c when they see "Agent", they think of out-of-process "Agent" (i.e. OpenTelemetry Collector/Agent). [btw, this confusion was mentioned way back in the very first OTEP]
I've sort of been trying to make "OpenTelemetry Javaagent" happen to help with this confusion, but I'd like to see what others think, if this is a big enough problem to deviate from the official Java terminology. While the JVM arg is -javaagent:... and so I don't think "Javaagent" is a huge stretch, I believe all official Java docs refer to these as "Java Agents", and not "Javaagents".
cc @open-telemetry/java-instrumentation-approvers
I remember that we had that discussion with another PR a few months back as well.
While it makes things much longer (and harder to read?) what about calling it "Java Auto Instrumentation Agent"?
Independent of what we use as a term, it might be got to have an explicit statement on that potential confusion in the documentation.
what about calling it "Java Auto Instrumentation Agent"?
do you know if this works for other languages? (e.g. .NET Auto Instrumentation Agent)
if so that's definitely a nice +
Heh, to make matters more confusing, .NET autoinstrumentation is explicit not an agent, but a set of runtime diagnostics hook...
do you know if this works for other languages? (e.g. .NET Auto Instrumentation Agent)
If you come from the APM world, yes, that works. Same for auto instrumentation for any other language. Reading through OTEP-1 I see that this already has some mentioning of that topic:
One way to navigate situations like these is with a software layer that adds OpenTelemetry instrumentation to a service without modifying the source code for that service. (In the conventional APM world, these software layers are often called “agents”, though that term is overloaded and ambiguous so we try avoid it in this document.)
APM vendors have called their way of auto instrumenting an application independent of the underlying technology as agent since ages now. I just checked "our" (AppD), NewRelic & the Dynatrace doc and we all have a "Java Agent", a ".NET Agent, a "python agent", a "node.js agent", a "php agent", etc.
Under the hood they all use different technologies, e.g. for java the byte code instrumentation is used and the agent is injected via javaagent, for .NET they use the runtime diagnostic hooks @cartermp was mentioning, for node.js there's a bunch of monkey patching & some C++ code, for php & python there is also some modules you can load.
However, the (APM) end-user doesn't care about the technical details, what they care about is the "auto-instrumentation" part that takes care of all the magic for them (e.g. finding methods that are worth to be decorated (with spans), creating metrics, taking care of log correlation, capturing errors, providing some deeper diagnostics, etc.
So for an APM end-user there is this mental model of "agent = auto instrumentation" independent of the language. I have encountered that multiple times myself and needed to talk about the differences between OpenTelemetry and APM agents.
To make a long story short, I think it would be important for us to have a docs page that talks about "Agents". This could also be the place to state the difference between an out-of-process agent-mode collector and the javaagent
How about "Java-agent"?
Why? Well, an ambiguity in "OpenTelemetry Java Agent" IMHO, is that the reader might not know how to parse this. To use parentheses to disambiguate, the two options are ((OpenTelemetry Java) Agent) and (OpenTelemetry (Java Agent)). The way we usually handle that in English is to use a hyphen. So "Java-agent" would make sense to me, and it's more readable than Javaagent -- which can work as a flag name, but not so well for use in prose. Thoughts?
