Instrumentation API is too tracing oriented

[breedx-splk]

When we first built the Instrumentation API, tracing was (and often still is!) on the forefront of developers' minds. Over time, it becomes more apparent that not all instrumentation is concerned with tracing. Some instrumentations only want to measure something...and some other instrumentations might only want to log a thing or emit an event when something interesting happens.

The latter is especially true in the client/mobile world. At the time of this writing, Android is using an odd mix of zero-duration spans serving as events and fledgling events (based on LogRecord). This isn't great, and an improved Instrumentation API could help to facilitate improvements here.

As evidence that the Instrumentation API is primarily concerned with tracing, take the example of the primary instrumentation API class: Instrumenter (link). The javadoc reads as though it encompasses all manner of instrumenting:

The {@link Instrumenter} encapsulates the entire logic for gathering telemetry [snip]

...but the builder() requires a SpanNameExtractor and assumes that all telemetry will have a span name! Furthermore, there are no methods dealing with logs nor events, and the metrics support is also minimal (geared at measuring tracing "operations" [like requests] and supportability metrics).

I haven't given this topic too much though and don't have a design approach yet. I think it would be great for us to begin thinking about what an extension/expansion of the instrumentation API might be -- and one that helps instrumentation authors (in the web/mobile space and beyond) to easily create non-tracing instrumentation that is implemented with consistency.

[trask]

related: open-telemetry/opentelemetry.io#6102 (comment)

I'm optimistic about future weaver developments to address this need [Instrumentation API] for end users

[Charlesnorris509]

@breedx-splk Your point about the Instrumenter class being tightly tied to spans is spot on. Right now, logging an event or recording a metric often requires unnecessary workarounds, which can be especially frustrating in mobile environments like Android.

I went through PR #6102, and it really highlights the need for clearer documentation and better support for non-tracing telemetry. I think your idea of expanding the Instrumentation API could be a great solution. Here are a few thoughts:

Unified Instrumentation Abstraction: A high-level TelemetryInstrumenter that supports tracing, logging, metrics, and events in one place.
Event-Centric API: A dedicated EventEmitter to log events without needing spans or LogRecord.
Backward Compatibility: Extending the existing Instrumenter to support multiple telemetry types.
Better Documentation: Clear examples for non-tracing use cases (e.g., logging user actions in mobile apps).
A formal design proposal or RFC could be a great next step to get community feedback and ensure the solution works for both web and mobile developers.

Thanks again for bringing this up

[breedx-splk]

Thanks @Charlesnorris509, for the reply and for some confirmation. Appreciate that. A few notes;

Event-Centric API: A dedicated EventEmitter to log events without needing spans or LogRecord.

I think there is room for that to happen, once the dust clears on logging over in the core repo. It may not be part of the specification, but languages are free to provide their own convenience APIs (or "syntactic sugar") to make things more idiomatic and more usable. We probably want a kotlin-based event API for Android as well.

A formal design proposal or RFC could be a great next step to get community feedback and ensure the solution works for both web and mobile developers.

I am pretty sure that because the specification doesn't address the instrumentation API, we can probably avoid needing a more formal rfc/spec for this. Instead, we can just think about doing parts of what you described incrementally. That also allows us (and the community) to try things out and provide feedback so that we can iteratively work toward stability.