align opentelemetry instrumentation naming with specification

[toumorokoshi]

Hi!

I recently worked with opentelemetry-specification to align on a standardized naming for instrumentations across languages. Here's the final result:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries

And the PR where it was discussed:

open-telemetry/opentelemetry-specification#539

I think if js followed the specification as written, it would have every package here renamed (replace "plugin" with "instrumentation")

opentelemetry-plugin-xml-http-request -> opentelemetry-instrumentation-plugin-xml-http-request
I wanted to raise this as a discussion as well as possibly a "bug": main question is: does this specification as written work for js?

• This only affects the JavaScript OpenTelemetry library
• This may affect other libraries, but I would like to get opinions here first

[dyladan]

If there is no established name, the recommendation is to prefix packages with "opentelemetry-instrumentation", followed by the instrumented library name itself. Examples include:

• opentelemetry-instrumentation-flask (Python)
• @opentelemetry/instrumentation-grpc (Javascript)

Since we already have some modules with established names, it looks like the spec does not require us to rename existing ones. At the very least, I think we could rename the folders within the repo (without renaming the actual packages). We can talk about renaming the packages, but I'm not sure how much value is really there to bring a change that might be confusing for existing users.

[toumorokoshi]

rah ok, the intention was more for if there was no convention for the specific package being instrumented, rather than some convention period:

An instrumentation library should be named to follow any naming conventions of the instrumented library (e.g. 'middleware' for a web framework).

If there is no established name, the recommendation is to prefix packages with "opentelemetry-instrumentation", followed by the instrumented library name itself. Examples include:

Maybe It would have served the intention better to combine them into the same paragraph. But more on topic...

I do agree that this is a disruptive change with no significant immediate benefits. One long term benefit: those who have to instrument multiple languages can rely on the package naming semantics to search (e.g. searching for "instrumentation", rather than knowing plugin == js).

But it could also be argued that one could search for "opentelemetry" and find all relevant libraries anyway.

I think there's enough cons that I won't argue further aside from noting this convention now exists. But if there are changes, pre-1.0 is the right time while things are still in flux.

Thanks for looking!

[dyladan]

@mayurkale22 and other @open-telemetry/javascript-approvers opinions?

[vmarchaud]

I agree with @toumorokoshi, if we want to make a changes, it need to be done before GA. I will be in favor of updating now and deprecating the old name

[toumorokoshi]

As a thought, this could be tackled the same time as #21