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.

[SergeyKanzhelev]

Discussed before: #30

[tsloughter]

I've been using "instrumentation".

How the instrumentation is included into what it instruments depends on the particular case, sometimes it is a plugin, sometimes an extension, sometimes a middleware, sometimes an interceptor.

[toumorokoshi]

Some more from the specification SIG meeting:

• how to call auto-collection modules #30 calls these "instrumentation adapters"
• @SergeyKanzhelev was considering rename the packages "adapters"
• @Oberon00 notes that the term "extension" in Python is currently encompassing both the adapters, and other hooks into the sdk such as exporters.

[toumorokoshi]

Based on what I've heard, I'd like to file a PR standardizing around the following hierarchy:

"opentelemetry/adapter/{instrumented library}"
"opentelemetry/exporter/{system that is being exported to}"

[SergeyKanzhelev]

also see this page https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-adapters

[arminru]

@tsloughter Good point! That's also what @tedsuo said back in the days on #30 (comment):

On the OpenTracing side, we usually just refer to these components as "instrumentation." As to whether that instrumentation is a plugin, a wrapper, an interceptor, or an adaptor, that usually depends on how the target library or framework actually works. Different frameworks have different names for their extensibility mechanisms. It could be native instrumentation as well, once adoption picks up.

They went for instrumentation adapter, however.

[arminru]

The OpenTelemetry glossary lists them as "Instrumenting Library" and mentions "Instrumentation Library" and "Integration" as synonyms.
Once we have finally settled for a term, the glossary and/or the overview.md saying "Instrumentation adapters" will need to be updated.

[tsloughter]

Instrumentation library makes more sense to me. I can't think of an example off the top of my head but "adapters" sounds like something similar to plugin, interceptor, middleware and may be used that way in places outside instrumentation. While "library" is just a generic term for a bundle of code.

[SergeyKanzhelev]

@mtwo need PM opinion here

[mtwo]

To me, "instrumentation" refers to any code that generates telemetry, which could be an "integration" that someone has written to instrument a shared library (RPC client, storage client, etc.), or OpenTelemetry API calls that an end-user developer has written to generate custom telemetry in their service.

Does that work for everyone else or did I muddy the waters even further?