In the Java prototype, SpanData has been exposed as an alternative way for an application to submit spans. This was justified as a means of forwarding spans constructed out-of-band, e.g., for transforming logs data into span records. I can't find the original discussion that led to this, but would like to formally propose removing SpanData from the user-facing instrumentation API because it is not meant for instrumenting.

In my view, SpanData is part of the default exporter--a part of the OpenTelemetry SDK specification, but not a part of the instrumentation API. There will be other implementations built for this API that target different exporter models, and requiring those exporters to accept SpanData inputs is a burden.

Specifically, in the Java prototype we have removed the ability to explicitly set a start time or an end time. This creates two hurdles, one for the implementor and one for the instrumentor.

1. An implementation of the API that does not directly export SpanData is forced to accommodate a new, otherwise unnecessary data type, which increases the size and footprint of the code. Say an implementation is designed to record low-level events to an external processor. To implement Span.recordSpanData requires emulating the events that would be recorded for that span, so they're going to have to accommodate spans with user-provided timestamps, but they have to implement two code paths since recordSpanData cannot be implemented in terms of other Span APIs.

2. An instrumentor is faced with a burden too. Suppose (using Go, for example) you're implementing gRPC middleware and want to use the golang.org/grpc/stats.Begin and golang.org/grpc/stats.End events to start and finish spans. You've been given correct start and end timestamps, but in order to use those you would have to construct a SpanData object, instead of calling Span APIs as you otherwise would.

The suggestion here is that it should be possible to implement recordSpanData in terms of the Span API. This means supporting new span options to set the start and end time. Then, recordSpanData can be implemented as a helper, which simply turns SpanData into a sequence of Span.Builder calls.

If there is a concern that it is difficult or awkward to translate out-of-band spans into Span API calls, we should focus on those problems specifically. In OpenTracing, the problem was that Resources were not a first-class part of the API, so it was confusing to think about forwarding spans through the Span API. With explicit Resources part of the API, we should be able to record out-of-band spans using the Span API.