Clarify inject/extract exceptions

The most common outcome of inject/extract methods that instrumentation needs to deal with are

1. success
2. unsupported format
3. empty carrier (extract only)
4. other exceptions (including invalid carrier type, corrupted carrier, etc.)

In Python API we specified exactly how tracer must react to these, specifically by throwing known exception for (2) and returning None for (3). The case (4) is usually a result of misconfiguration, so the exact exception is not that important.

I would like to have a well-defined (unchecked) exception type for (2), and specify that null must be returned for (3).

Side note: inject() documentation refers to carrier types instead of formats: @param carrier the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

@bensigelman @michaelsembwever

[michaelsembwever]

NoopSpanBuilder is not part of the API

Exactly. From the API perspective all you see is an empty SpanContext.

I’m sorry, but returning null is just a really poor way of solving this, and definitely shouldn’t be enforced at the API level.

[tedsuo]

Spring cleaning here: closing this issue as it is out of date, and many things have changed since the debate stopped. Feel free to reopen this issue or create a new one if you would like to continue.