Closed svrnm closed 4 weeks ago
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)
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:
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.
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.
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.)
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.
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:
Here is a suggestion (and we can work from there):
<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>
.<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. <term a>
to describe that extension, but not the extended app. It may be called "first-party extension" but not "official extension".<term a>
or <term b>
<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:
<term a>
= otel-ready
and <term b>
= otel-compatible
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"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?
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).
@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
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 ?
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 https://github.com/open-telemetry/opentelemetry-specification/issues/4129#issuecomment-2278047024: 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?
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.
What are you trying to achieve?
To kick off the effort of what was described in https://github.com/open-telemetry/community/issues/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