Remove SpanData

[bg451]

Motivation

The goal of this change is to remove SpanData from the API specification and replace it by adding span start and end options. SpanData, from what I could see, had two primary use cases in mind. The first involved building out of band spans from different sources such as logs. The second was to allow deferred span creation, for example, receiving the first byte in a request, taking the time of that, parsing the headers, then finally creating the span with that first byte timestamp.

Changes

References to SpanData have been removed.

For span start options, we are adding an optional timestamp to specify the start time, a resource to override the tracer's resource, and span ID to support out of band reporting.

For span end options, we are adding an optional timestamp to specify the end time.

Maybe it's out of scope for this specification change and i can remove it, but I've also added an optional timestamp when adding events to support out of band events as well. See #213 for an example use case.

Original RFC discussion: open-telemetry/oteps#8
Merged RFC: https://github.com/open-telemetry/rfcs/blob/8dd6e21/text/0002-remove-spandata.md

[bg451]

This is an open question for me and I'm not quite sure what the solution is. I'd love to get your input and ideas @bogdandrutu and @tylerbenson

[jmacd]

I think we should just say that when using an explicit start time, we recommend also using an explicit stop time, otherwise there is a chance that the clock readings are not comparable. If pressed, I would add that individual languages may decide to support >1 kind of timestamp where appropriate. E.g., In Python there is time.time() and time.time_ns() and both could be supported in some way.

[carlosalberto]

Sounds like we should add End timestamp to the member list here as well.

[bg451]

I suspect I should just remove this todo altogether and just add a tidbit about languages recommending which clock should be used if supplying timestamps (assuming there's more than one way e.g. javascript and python). Does that seem like a reasonable solution?

[bogdandrutu]

I think we don't have the RFC approved, as per suggestion from @iredelmeier and @jmacd we merge all RFC with a proposed status and later we approve them (my initial thought was that once we merge the RFCs are approved or denied, but that is not the case) so please do a PR that changes the status to approved for that RFC before merging this.

I am not sure what is the process with RFC because I am not the one who proposed this process, so not clear for me what do we need to do to approve RFCs.

[carlosalberto]

Left a note about possibly adding End timestamp as part of this PR - that aside, it all looks great!

[bogdandrutu]

Please rebase. There are a lot of changes in this doc already merged :)

[arminru]

The RFC says:

From #71: If the underlying SDK automatically adds tags to spans such as thread-id, stacktrace, and cpu-usage when a span is started, they would be incorrect for out of band spans as the tracer would not know the difference between in and out of band spans. This can be mitigated by indicating that the span is out of band to prevent attaching incorrect information, possibly with an isOutOfBand() option on startSpan().

This flag/option is missing in this PR.

You noted above:

For span start options, we are adding an optional timestamp to specify the start time, a resource to override the tracer's resource, and span ID to support out of band reporting.

When spans are created asynchronously, e.g. from received messages or by reading a log file (see use cases described in #71), a Span ID will have to be generated at span creation and can therefore not be used to indicate that the span is reported out of band.

[bogdandrutu]

Approvers please approve this PR. I think this is a trivial (and good) change applying the already approved RFC.

[songy23]

LGTM

[bogdandrutu]

Start timestamp will not be removed :)

[bg451]

Oops will fix right now

[bg451]

fixed :)

[carlosalberto]

No End timestamp btw? ;)

[Oberon00]

This is the section for span creation. The span end timestamp is mentioned here: https://github.com/open-telemetry/opentelemetry-specification/pull/215/files#diff-ea4f4a46fe8755cf03f9fb3a6434cb0cR373

[songy23]

Please rebase.

[bogdandrutu]

Please follow what it says here https://github.com/open-telemetry/opentelemetry-specification/pull/215/checks?check_run_id=216754717

While I am trying to understand why DCO was added as a check please do this to not block this PR.

[bg451]

Cool fixed DCO

[yurishkuro]

not sure what " and MAY be used as an argument" means. Is it needed here?

[bg451]

Hm yeah it doesn't read well, I don't think it's needed.

[reyang]

LGTM.