Instrumenting libraries with OpenTelemetry

[anuraaga]

I was wondering if people have thoughts on how we expect libraries to use OpenTelemetry to instrument themselves. Let's just talk about spans though the same should apply to most aspects. Would we expect a library author to call OpenTelemetry API directly within their business logic, or define an interceptor API and implement an OpenTelemetry version of the interceptor.

For example

Context context = instrumenter.onStart(Context.current(), request);
makeRpc();
instrumenter.onEnd(context, response);

(I've used the in-progress Java instrumenter API instead of OpenTelemetry API directly as it also can allow arbitrary request listeners similar to the below example).

vs

for (Interceptor interceptor : interceptors) {
  interceptor.beforeRpc();
}
makeRpc();
for (Interceptor interceptor : interceptors) {
  interceptor.afterRpc();
}

I feel as if only the second option is really viable right now, because the OpenTelemetry API, while cheap, is not no-op. In particular, we see Context.current() would already incur reasonable overhead on Java, making it a no-go to ensure users can use the library without penalty when they don't need OpenTelemetry. However I think there may be a goal of the project to encourage the first form. Is that feeling accurate? And if so, any thoughts on if it's practical? I can only imagine it being possible on a major version upgrade to OpenTelemetry with making Context also no-op by default.

For reference, I have implemented an experimental extension for Java that is truly no-op by turning off Context as well

https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/noop-api/src/main/java/io/opentelemetry/extension/noopapi

This can be used when there is strong control over the end-user experience, such as in a team's batterys-loaded server framework - I will try to use this for more native integration into some high-risk frameworks. But it still wouldn't be appropriate as a default for a random client library which can't force Context to be off like this.

[yurishkuro]

I think the 2nd form is preferable, if the library can be instrumented via interceptors/middleware it speaks of better design compared to having to mix the instrumentation code inside the library. However, sometimes the question of context propagation / threading might come up, e.g. when post-request interceptors run in a different thread.