This method is here for the (hopefully rare) cases where you want to start a new span but don't control the
context where your code is executed (e.g. a third party library) - this method will start a new overall request
span or a new subspan depending on the current thread's span stack state at the time this method is called.
In other words this method is a shortcut for the following code:
Tracer tracer = Tracer.getInstance();
if (tracer.getCurrentSpanStackSize() == 0) {
return tracer.startRequestWithRootSpan(spanName);
}
else {
return tracer.startSubSpan(spanName, SpanPurpose.LOCAL_ONLY);
}
This method assumes
SpanPurpose#SERVER if the returned span is an overall request span, and
SpanPurpose#LOCAL_ONLY if it's a subspan. If you know the span purpose already and this behavior is
not what you want (i.e. when surrounding a HTTP client or database call and you want to use
SpanPurpose#CLIENT) then use the
#startSpanInCurrentContext(String,SpanPurpose) method instead.
WARNING: As stated above, this method is here to support libraries where they need to create a span
for some work, but do not necessarily know how or where they are going to be used in a project, and therefore
don't know whether tracing has been setup yet with an overall request span. Most of the time you will know where
you are in relation to overall request span or subspan, and should use the appropriate
Tracer.startRequestWith*(...) or
Tracer.startSubSpan(...) methods directly as those methods spit
out error logging when the span stack is not in the expected state (indicating a Wingtips usage error). Using
this method everywhere can swallow critical error logging that would otherwise let you know Wingtips isn't being
used correctly and that your distributed tracing info is potentially unreliable.
This method is the equivalent of swallowing exceptions when Wingtips isn't being used correctly - all
diagnostic debugging information will be lost. This method should not be used simply because it is
convenient!