Instrumentation API

[anuraaga]

Proposal for an instrumentation API to assist in providing high quality, consistent instrumentation.

[anuraaga]

Related issues

@zionsofer https://github.com/open-telemetry/opentelemetry-specification/issues/1724 - wanting callbacks for adding attributes to instrumentation

@jmacd https://github.com/open-telemetry/opentelemetry-specification/issues/464 - dedicated instrument for timing. Possibly more appropriate for an instrumentation API having the concept of operations than the core API itself

@jkwatson https://github.com/open-telemetry/opentelemetry-specification/issues/1747 - span modeling. I didn't include the shouldStart method we currently have in the Java prototype because span modeling is still not well defined. But it should be possible to capture such modeling in the instrumentation API without having to expose the confusion to instrumentation authors, I think

[carlosalberto]

There's a related group that may be responsible/help with this. @tedsuo ping

[ahayworth]

I think one aspect that you may not have considered is the third goal - "Provide a consistent user experience for users of instrumentation".

All of the goals in this are really good, but this one is in tension with the others. That dynamic is definitely what we need to figure out: how to balance quality experience for the users against the ease of implementation for third-party library authors. The potential downsides are pretty large, too - if we make it too difficult for third-party library authors, then they will likely not do it (foisting the work directly back onto the OpenTelemetry community to maintain the instrumentation, rather than spreading it around).

The intent of the code is definitely to illustrate the concepts and maybe actually writing out method signatures was too much.

That's a reasonable point, and I think maybe I agree too. Part of what makes this difficult for me to support is the how specific it already is in implementation details. For example, I might be able to build something that fulfills the spirit of what we're trying to do here in ruby, but do it in a way that is idiomatic and comfortable for language authors - but not if I had to implement the specific contracts and patterns that this lays out.

Contracts that push, if not force, instrumentation authors to consider all the OTel semantic conventions when writing instrumentation. To ensure high conformance with OTel spec and data fidelity.

We should probably be careful with this? Attributes - and as far as I know, even using the ones defined in the Semantic Conventions - are optional. The specification even says "In OpenTelemetry spans can be created freely and it’s up to the implementor to annotate them with attributes specific to the represented operation."

So while we want people to use those attributes, we should be careful not to require them from folks, because we haven't really agreed that they are required otherwise. Not to mention, the semantic conventions are still "Experimental" at this point, anyways.

I think we'd probably do better at making it easier to use the right semantic conventions, rather than forcing people to use them?

[lzchen]

Has there been any discussion on how to handle instrumenting more than once to avoid duplicate telemetry? In Python we simply utilize a property on the base class that all instrumentations share. Probably would be something cool to have in the API.

[anuraaga]

@ahayworth Thanks - going to rewrite much of this to remove code and focus more on the concepts and use cases in a bit.

@lzchen We have https://github.com/open-telemetry/opentelemetry-specification/issues/1747 - indeed, such a concern can ideally be handled by this instrumentation API / infrastructure rather than each library instrumentation having to do it.

[jmacd]

focus more on the concepts and use cases in a bit.

@anuraaga I'm starting to understand the concepts and use-cases in this OTEP.

The biggest area for research and discovery that I see here is the point that we have two correlated problems: (1) the need for an idiomatic API for creating complex instrumentation which is sensitive to cost, (2) the need for a way to configure which instrumentation takes effect at runtime through a declarative configuration.

I have a feeling the APIs that result from this work could end up being language-specific, but that there are general concepts to be found. What if we focus on the second part first-- configuration-- under the assumption that every language SIG will find its own idiomatic API?

[carlosalberto]

I have a feeling the APIs that result from this work could end up being language-specific, but that there are general concepts to be found. What if we focus on the second part first-- configuration-- under the assumption that every language SIG will find its own idiomatic API?

+1 to this - even if the first part could easily be done for all languages, the second one (configuration) seems to be more important right now.

[srikanthccv]

I have a feeling the APIs that result from this work could end up being language-specific, but that there are general concepts to be found. What if we focus on the second part first-- configuration-- under the assumption that every language SIG will find its own idiomatic API?

+1 to this - even if the first part could easily be done for all languages, the second one (configuration) seems to be more important right now.

I second this. There is a varying difference between each SIG in terms of config part. For example ability to ignore tracing certain routes (/health) in web framework, request & response hooks to customise more attributes, and many other. The use cases are mostly same across languages and can be better uniformly defined to make it lot easier for instrumentation users and potentially the library authors.

[anuraaga]

Thanks - I agree that configuration for the end user and developer experience for instrumentation authors are probably separate topics, and the former would have more shared concepts across languages or a set of shared knobs.

Developer experience for instrumentation is also important, but perhaps communicating data that is shared among concepts (HTTP route used both as attribute and span name) is not quite as important as having a good test suite per semantic convention namespace, which could potentially even be implemented out of process.

[tedsuo]

@anuraaga we are marking OTEPs which are no longer being updated as stale. We will close this PR in one week. If you wish to resurrect this PR, that is fine.