Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
toumorokoshi opened this issue Feb 19, 2020 · 22 comments · Fixed by #539
Closed

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

toumorokoshi opened this issue Feb 19, 2020 · 22 comments · Fixed by #539
Milestone

Comments

@toumorokoshi
Copy link
Member

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:

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

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
Copy link
Member Author

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
Copy link
Member

arminru commented Mar 5, 2020

#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
Copy link
Member

Oberon00 commented Mar 5, 2020

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

@toumorokoshi
Copy link
Member Author

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.

@Oberon00
Copy link
Member

Oberon00 commented Mar 10, 2020

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

@arminru
Copy link
Member

arminru commented Mar 10, 2020

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
Copy link
Member Author

toumorokoshi commented Mar 14, 2020

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member Author

toumorokoshi commented Mar 19, 2020

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
Copy link
Contributor

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

@SergeyKanzhelev
Copy link
Member

SergeyKanzhelev commented Mar 24, 2020

Discussed before: #30

@tsloughter
Copy link
Member

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
Copy link
Member Author

toumorokoshi commented Mar 24, 2020

Some more from the specification SIG meeting:

@toumorokoshi
Copy link
Member Author

toumorokoshi commented Mar 24, 2020

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}"

@arminru
Copy link
Member

arminru commented Mar 24, 2020

@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
Copy link
Member

arminru commented Mar 24, 2020

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
Copy link
Member

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
Copy link
Member

@mtwo need PM opinion here

@mtwo
Copy link
Member

mtwo commented Mar 26, 2020

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?

toumorokoshi added a commit to toumorokoshi/opentelemetry-specification that referenced this issue Mar 31, 2020
Fixes open-telemetry#476

A single term for instrumentation libraries would be beneficial, as
it reduces ambiguation. Removing synonyms "integration" and "adapter".

Integration doesn't imply some form of instrumentation, while adapter
could easily overlap with middleware or other concepts in existing
frameworks that will be instrumented.
SergeyKanzhelev pushed a commit that referenced this issue May 18, 2020
* normalize term for instrumentations

Fixes #476

A single term for instrumentation libraries would be beneficial, as
it reduces ambiguation. Removing synonyms "integration" and "adapter".

Integration doesn't imply some form of instrumentation, while adapter
could easily overlap with middleware or other concepts in existing
frameworks that will be instrumented.

* Addressing feedback

Using the full "instrumentation libraries" form where possible.

Fixing capitalization of OpenTelemetry.

Adding reference to "Instrumenting Libraries".

Adding link to definition in overview

* finishing cleaning up merge errors.

* fixing for lint.

* re-removing milestones

* Update specification/glossary.md

fixing typo

Co-authored-by: Giovanni Liva <[email protected]>

* Addressing feedback

Re-adding a section clarifying the goal of opentelemetry to
enable native instrumentation.

Fixing links.

* rewriting first paragraph on instrumentation libraries

Clarifying several aspects about instrumentation libraries.

* Update specification/error-handling.md

Co-authored-by: Morgan McLean <[email protected]>

Co-authored-by: Giovanni Liva <[email protected]>
Co-authored-by: Morgan McLean <[email protected]>
@carlosalberto carlosalberto added this to the v0.5 milestone May 28, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

8 participants