[Terminology] Add a term to the glossary that describes when "Instrumented Library_and Instrumentation Library are the same"

[svrnm]

What are you trying to achieve?

To kick off the effort of what was described in open-telemetry/community#2165 I'd like to request that we add a term to the specification glossary that describes the case where Instrumented Library and Instrumentation Library may be the same library if it has built-in OpenTelemetry instrumentation.

A term often used for that is native instrumentation, but other terms have been suggested, since "native" might mean lots of things that are unrelated to technical aspects".

Goal: We need this term for the documentation to describe the process of adding OpenTelemetry to a library for out of the box telemetry. We also want to use it for the registry to tag entries of "native" instrumentations. So a term that is easy to understand even without the word "instrumentation" would be helpful (like 'native', 'out of the box', etc.), e.g. for the "Instrumentation for Next.js", see https://opentelemetry.io/ecosystem/registry/?s=next.js

The case where an application comes with OpenTelemetry out of the box (like some K8s System Components) needs also to be covered or explicitly excluded.

The term should also make it clear that it is the opposite of when instrumentation is added externally, e.g. by an instrumentation library.

cc @open-telemetry/docs-approvers @open-telemetry/technical-committee @open-telemetry/governance-committee

[trask]

to me, I would like "natively instrumented library" to mean that everyone who is using that library who is also using the OpenTelemetry SDK will get telemetry from the library emitted by default through their OpenTelemetry SDK (without any further steps such as installing an optional library module)

[svrnm]

to me, I would like "natively instrumented library" to mean that everyone who is using that library who is also using the OpenTelemetry SDK will get telemetry from the library emitted by default through their OpenTelemetry SDK (without any further steps such as installing an optional library module)

Thanks, that's a good description for it! Would you also say that a "natively instrumented application" means that everyone who is using that application and adds opentelemetry configuration (right now environment varialbes) will get telemetry from the library emitted by default?

---

To add that, please take a look at https://opentelemetry.io/ecosystem/integrations/, we have here a mix of things:

• "Natively instrumented libraries" as you described them (e.g. Next.JS, EleasticSearch Java API Client)
• "Natively instrumented application" as I described them/if we want to name them like that like Kubernetes Core Components, Buildx, Buildkit)
• Applications with a "first party plugin" (i.e. provided by the same vendor/project) like MySQL Server, nginx, roadrunner, matlab, jenkins
• Libraries with a "first party instrumentation library" (i.e. provided by the same vendor/project) like Cerbos JS SDK
• SaaS services that provide functionality to export their telemetry via OTLP (like Cisco ThousandEyes)
• Other observability libraries like Micrometer that integrate OpenTelemetry

From my understanding only the first 2 are "native"? Or only the first, if we use a different terminology for applications that come with opentelemetry out of the box.

[austinlparker]

I would generically suggest that your third point - plugins provided by the upstream authors - are also "native". Perhaps "integrated" captures the spirit better?

For instance, imagine two HTTP servers, one of which integrates the OpenTelemetry API from the jump to provide telemetry data, and one which has a custom API that supports plugins to transform that data. Would it be incorrect to say that the second also has 'native' OpenTelemetry assuming that the outputs are the same from both? I don't necessarily think so.

[theletterf]

Would OTel-ready, as an adjective, be comprehensive enough of situations where something can be used with OTel right away? (I was about to suggest OTel Inside, but that would have forced me to see myself out.)

[danielgblanco]

Would it be incorrect to say that the second also has 'native' OpenTelemetry assuming that the outputs are the same from both?

I think it would be confusing to say that the second case is "native". For end-users the fact that an application is "OTel-native" should give them the assurance that it supports SDK config (via env vars or file config) and will automatically benefit from future releases of the SDK as provided by OpenTelemetry, without the need for the application owner to provide extra support. I can imagine the case where an application advertises that it uses OTel SDK version x.y.z but it does not support (or allow config of) certain features. After all, applications that use OTel SDK do not require to be compliant with the spec. IMO this would not be a great experience. Would an application stop being "OTel-native" if it upgrades to a version of the OTel SDK but it does not support certain config or features provided by the OTel SDK in that version?

Evolving on @trask's definition above, and changing OTel-native to OTel-ready as @theletterf (which I quite like), I'd personally see it as:

Everyone who is using an OTel-ready library who is also using the OpenTelemetry SDK will get telemetry from the library emitted by default through their OpenTelemetry SDK (without any further steps such as installing an optional library module), and everyone who is using an OTel-ready application will be able to use and configure all features of the OpenTelemetry SDK using standard OTel mechanisms supported by the relevant SDK version.

[svrnm]

Thank you all for engaging in this discussion. As it seems there are a few nuances we need to get right. Just to get back to this, there are multiple things we have at hand right now and we are free to decide if we put them all under one umbrella term or if we use different terms:

1. How do we call a library that takes direct dependency of the OpenTelemetry API and by that is instrumented and instrumenting library at the same time? (Example: gRPC)
2. How do we call an application that includes the OpenTelemetry SDK (and by the the API as well) and by that it is possible to configure it through "default SDK configurations"? (Example: Docker Buildx and Buildkit. Do we want to use the same term as for (1)? Do we need a way to distinguish between "they do otel somhow" and "they do otel the 'right' way"?
3. If an ecosystem related to an application has a commonly used extension mechanism, and there is an extension that adds opentelemetry support to that app, how are we calling that? Are we distinguishing it if it comes from a first party vendor or a third party? (Example: nginx modules: (by C++ Contrib, by F5/nginx) Are we using the same term as for (1) and (2) or yet another one? Does that term describe the extension or the thing that got extended? ("nginx is otel-ready" vs "nginx has an extension that makes it otel-ready")
4. Do we want to provide an additional name for instrumentation libraries that are provided "first party"?
5. Do we provide an umbrella term (https://opentelemetry.io/ecosystem/integrations/)

Here is a suggestion (and we can work from there):

1. We have <term a> for libraries that come with opentelemetry out of the box by taking dependency on the official opentelemetry API and by that will get telemetry by using the OTel SDK. If they provide opentelemetry compatible telemetry through other means but still out of the box (so no instrumentation library is needed), it is something different. We provide <term b> for that "different" as well. Also <term b> includes <term a>.
2. We use <term a> for applications if and only if it comes with the official OTel SDK and provide configuration through official SDK configuration (env variables now, config files later), they may provide alternatives, but if they wrap everything or and you need to go through a different route of configuring otel, or if they use a third party implementation of otel, it is<term b> again.
3. Same applies for the extensions: if and only if they use otel api/sdk as they are intended to be used they can use <term a> to describe that extension, but not the extended app. It may be called "first-party extension" but not "official extension".
4. I would say, same applies here, if a vendor provides such an instrumentation library, they can call it "first party instrumentation library" (not "official"), but it is not neither <term a> or <term b>
5. We use <term b> as umbrella term.

Does this make sense? I purposefully did provide placeholders for the terms, as it is about the definition not the terminology, but since it makes it hard to read, here is a suggestion(!) on that terminology and we can iterate on that:

0. <term a> = otel-ready and <term b> = otel-compatible
1. By taking direct dependency on the otel api, gRPC is otel-ready. If next.js decides to move from otel api to a replacement like otelzero it will be "otel-compatible" but not "otel-ready"
2. By using the sdk and allowing end-users to configure their app using the sdk config, Docker Buildx/Buildkit are "otel-ready". Under that definition K8s would be otel-compatible, since they provide a specific way to configure
3. The OpenTelemetry extensions for nginx are all "otel-compatible" because although they take direct dependency on the SDK they all provide non-standard ways to configure the SDK and by that not all features are accessible out of the box. nginx itself is neither "otel-compatible" or "otel-ready", since it requires an extension for that. One might be able to say "the extension makes nginx otel-compatible"
4. x
5. On the integrations website we write about "otel-compatible" and "otel-ready" and can list that accordingly per item.

Note that this is our terminology, so we enforce this within the project, we kindly ask people outside the project to use it accordingly, but if people do it differently 🤷‍♂️

Did I forget anything? What terms do we want to use?

[codefromthecrypt]

My 2p is that we want to encourage first party ownership and native is a subset of that. For example, if an org has an otel repo, maintained by the same owners as the primary product, that's first party even if it isn't built-in/native.

So, effectively I would lean into a square/rectangle analogy of native/first party where the ownership is the driving concern. The next best to that is instrumentation owned by otel either in a main or contrib repo. Basically, these are the two best buckets to encourage even if there is nuance between native (I think built-in) and first party (I think "ready", but still owned by the authors).

[svrnm]

@open-telemetry/technical-committee can you help and steer this discussion please. The goal is to have the terms defined in the glossary eventually such that we can use them in Docs and other community writings

[jsuereth]

TC Triage: This is important to decide and needs to be driven into the Specification. We recommend bringing this issue to the Specification meeting to have a broad discussion and see if we can make progress before escalating to a private discussion.

This will need a sponsor, is that @svrnm ?

[svrnm]

TC Triage: This is important to decide and needs to be driven into the Specification. We recommend bringing this issue to the Specification meeting to have a broad discussion and see if we can make progress before escalating to a private discussion.

This will need a sponsor, is that @svrnm ?

Same answer, as in #4129 (comment): I will try to attend a Spec Meeting, but they unfortunately collide with an internal meeting I have a hard time to skip. Not sure if a GC-member is in the list of potential sponsors? I am OK with driving this by providing a proposal in a PR, but I guess a spec sponsor needs to sponsor that?

[tigrannajaryan]

I like “natively instrumented” and I think it should be used only for code that has Otel API calls embedded (applies to libraries and applications).

A separate library that instruments another library is not “native instrumentation” it is a “bolt-on/add-on/sidecar instrumentation” (even if both are written by the same authors).

We need to encourage library and application developers to maintain the instrumentation as a first-class concern in their codebase and I think we need to reserve “natively instrumented” label as a badge of honor that only applies to these cases.