standardize on a name for plugins/extensions/integrations/instrumentations

[toumorokoshi]

There's a concept that's mentioned a few times in the spec, but doesn't have it's own explicit section, around the glue that binds opentelemetry to some specific framework, db, or some other core system.

In the spec, it has been referred to as instrumentations and integrations:

• integration: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#distributedcontext
• instrumentation/integration: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-metrics-user.md#obtaining-a-meter

In various repositories, they are referred to as "plugins" or "extensions":

• "plugins": https://github.com/open-telemetry/opentelemetry-js/tree/master/packages
• "extensions": https://github.com/open-telemetry/opentelemetry-python/tree/master/ext

It would be great to choose one word for this concept, and maybe add it's own page, or glossary term, to ensure the definition is clear.

[toumorokoshi]

Looks like "instruments" is being used in the metric api spec. As such, I'd vote against "instrumentations" as the term for this concept: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-metrics-user.md#new-constructors

[arminru]

#497 added a glossary to the spec: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md
This would be the right place to document the outcome of this discussion once we can settle on a term.

[Oberon00]

I think an instrument is something different from an instrumentation. An instrument is the API object used by an instrumentation to record metrics.

[toumorokoshi]

I think an instrument is something different from an instrumentation. An instrument is the API object used by an instrumentation to record metrics.

I think that distinction is clear in the specification, but I worry that the names are very similar (with one just being a different word stem than the other).

I would immediately assume that "instrument" and "instrumentation" relate to the same feature, not that they related to metrics and library that instrument other libraries. Choosing one of the three other synonyms would ensure that meaning is clear.

Also an aside, but "instrumentation" is hard to type, especially vs something like plugin.

[SergeyKanzhelev]

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

[Oberon00]

This term is news to me, I've never heard or seen anyone using it. This document seems to be its only usage.

[arminru]

To me, instrumentation adapter sounds like an adapter between two existing instrumentation APIs (cf. adapter pattern). When I'm instrumenting my app or library I'm writing an instrumentation, not just an adapter.

However, I think it is most important to settle on one term that we can all live with. This makes talking about it a lot easier and is less confusing for people reading the spec or checking out the language implementations.

[toumorokoshi]

I think an instrument is something different from an instrumentation. An instrument is the API object used by an instrumentation to record metrics.

If this is the case, would a "tracer" count as an instrument? As it is also used by an instrumentation.

However, I think it is most important to settle on one term that we can all live with. This makes talking about it a lot easier and is less confusing for people reading the spec or checking out the language implementations.

Agreed.

I think instrumentation is an appropriate word, but it's very long and a bit hard to type. I think with that perspective, "plugin" is the simplest choice.

• opentelemetry-plugin-flask
• opentelemetry-plugin-http

[Oberon00]

I think plugin is bad because it is a very generic term that could mean a lot of different things too. Like "library plugin": An instumentation for a library or a does the library itself have a plugin concept (like a thumbnailing library with a plugin for JPEG).

[Oberon00]

I'm in favor of Instrumentation. That term is also already in opentelemetry-proto (InstrumentationLibrary.name reports the name of the "plugin/extension/integration/instrumentation").

[toumorokoshi]

I'm not super averse to that, although I think it adds more to the package name.

I guess maybe I'll file a PR to try to specify some naming conventions around such packages, to ensure discoverability.

[fbogsany]

#30 introduced the terms "adapter" and "instrumentation adapter". There's some relevant discussion in that issue.