Add start time and duration (or end time) options on Span

[rochdev]

Right now the start time and end time are always calculated internally. While this works in most cases, there are cases where it needs to be set explicitly.

The most common use case is to reconstruct a trace from tracing metadata received from another process. This is how apollo-tracing works for example.

This is also an option that is available with OpenTracing so it needs at the very least to be available internally. But as described above, it should also be part of the public API to enable use cases where tracing data was generated externally.

For the end time, it could either be provided explicitly or the duration could be provided instead and then the end time can be calculated. In general, I think the duration should be preferred since it will allow languages with less precise integer types to still have high resolution. This is assuming that exporters are sending the duration to the agent/backend and not the end time.

[jmacd]

I think we can merge the current SpanData concept with OpenTracing-style StartSpanOptions to address this issue and shrink the API surface, we're working on an RFC. @bg451

[tigrannajaryan]

@bogdandrutu do you remember we also discussed the need for this in OpenCensus context (this PR: census-instrumentation/opencensus-java#1906). I have also just had use case described to me that requires this same functionality:

An instrumented application receives operation information from external devices via a proprietary API that cannot be changed. The application needs to generate corresponding span data that describes this operation on behalf of the external device using OpenTelemetry language library. The span start/end times are known to this application, but they are not "now", this information is received via the proprietary API.

Is there anything preventing us from making start time an user-specified option for span Start() and end time an option for End()?

[bogdandrutu]

Having a start and end timestamps was approved in the SpanData RFC. About out of band reporting I proposed a different RFC to remove that support because the agent can be used. There is still a need for start/end timestamps.

[tigrannajaryan]

@bogdandrutu thanks, I didn't know about the RFC. I can see that this RFC proposes to add ability to specify start and end time: https://github.com/open-telemetry/oteps/blob/master/text/0002-remove-spandata.md

The state of the RFC is approved, do we intend to have this in 1.0 specs? From what I see the current Tracing API spec does not provide any facilities for user-specified times.

[bogdandrutu]

See #215. Yes we want to have this. But I also think open-telemetry/oteps#26 should be included.

[SergeyKanzhelev]

This was completed. Events and Span Start/Stop APIs accept timestamps now