Guidance for instrumentation authors of libraries built upon other instrumented libraries

[alanwest]

Often libraries are built on top of other libraries. We currently have a few examples that, when both libraries are instrumented, different design decisions have been made.

Examples

Grpc.Net.Client & HttpClient

We have instrumentation for both. When both are configured they each individually create a client span.

AspNetCore & Grpc.AspNetCore.Server

Currently, our instrumentation for Grpc.AspNetCore.Server piggybacks on our standard instrumentation for AspNetCore. It does so by adding additional RPC attributes to the activity created by the AspNetCore instrumentation. It does not create an additional span.

AspNetCore & HotChocolate.AspNetCore

Hot Chocolate is a graphql framework. Similar to our Grpc.AspNetCore.Server instrumentation, it contains native instrumentation which piggybacks on the activity created by AspNetCore instrumentation and alters its name. There exist graphql semantic conventions for spans, but the conventions do not currently specify the span kind for a graphql server span. See #5402 for more details.

Things to discuss

• Do the differences in design decisions make sense? Or should we converge on one pattern over the other?
  • One of the problems with the "piggybacking" design is that instrumentation can be brittle as there is an implied contract between the instrumentation of the two libraries.
• Depending on what we decide, we should offer guidance to library authors.
• The examples above are primarily focused on span data. How (if at all) would our guidance affect metrics? (e.g. if we added support for the rpc.server.duration metric or if graphql eventually defined metrics).
  • Should both metrics be emitted? Or should we prefer one over the other?
• Is there a precedence in any other languages?
• Should this be a language/framework specific conversation, or should this be a topic be elevated to the semantic conventions SIG?