Add SpanData type

[danielkhan]

This adds the SpanData type that is also needed to implement Tracer.
Todo: Add an event type.

[draffensperger]

What would you think about having this just be a structural object type, so something like

export interface SpanData {
   name: string;
   kind: SpanKind;
   ...
}

The advantage of a structural type is that you can easily create it and it also doesn't take extra JS code for the methods that would be added to the JS bundles (especially relevant for browsers)

[danielkhan]

@draffensperger I did it like that because SpanData MUST be immutable.
So modeling it this way in TypeScript made sense to me.
But I am not a TypeScript wizard and I can also imagine simply using readonly for the properties. What do you think?

[draffensperger]

What's the motivation for making SpanData immutable? My understanding is that is important for multi-threaded languages like Java/Go (looking at Concurrency and Thread-Safety of OpenTelemetry API).

However, in Node and the browser, due to the evented model, it's not actually possible for two threads to modify the same object, so the concerns about immutability for the sake of thread safety don't apply. (Multiple threads can mutate a SharedArrayBuffer, but that's a low level type, whereas objects get cloned when passed between say the browser UI thread and a WebWorker).

Would there be another reason for making this immutable besides thread safety?

Having the types be readonly is a nice way to document and enforce immutability if all consumers of the API used TypeScript, but for plain JS users of the API, the readonly just gets compiled away. So I agree that having getter methods or even get property accessors is the way to go if we need immutability.

[danielkhan]

SpanData is used to report out-of-band spans. The spec emphasizes the immutability of the members and also the members' contents if they are compound types.

Example:
SpanData is passed into the tracer.
Now let's assume that this is not immediately passed to the exporter but buffered somewhere.

If someone starts to modify the object itself after it has been passed to the tracer - like setting new links or another resource or just changing SpanKind - the exported Span would be different from what has been passed to the tracer in the first place because of pass-by-reference.

Or let's say that links or context is changed somewhere else while the Span has not yet been exported.
The spec demands to make sure that this must not happen.
To tackle compounds, we might even need to clone the objects.
This is also emphasized in the spec.

This is why I kept the immutability rule to make sure that implementors are fully aware of that.

This may be a fallacy - I'm open for discussions.

[draffensperger]

Thanks for explaining more of how this would be used! Makes sense on immutability making it more clear that you can't modify it after passing to the tracer, and that it keeps consistency with other languages.

I still have some lingering feelings of wishing this could just be a structure, but I think I can put those to rest particularly if others like this design. I also just learned about Object.freeze, and wonder if that could help us in some way.

[danielkhan]

SpanData is specified here.

I need SpanData in Tracer as specified here.

Here is the discussion and Sergeys reasons to keep it like that for now.

[rochdev]

I feel like LocalContext is kind of same as SpanData.

SpanData and LocalContext are 2 different things. SpanData is used only for exporters, while LocalContext is to be used within the tracer.

I strongly disagree with this design. It's a prime example of over-engineering. In its current state, it also doesn't provide a way to access the LocalContext, so how can vendor-specific properties be retrieved? Having only a single SpanContext to hold everything would be much simpler and easier to work with, both for vendors and for users. Especially since the 3 classes will basically hold the same kind of information and return them in different ways, which is unnecessary and confusing.

As @draffensperger mentioned, the main goals of immutability are specific to threaded languages, and there are no reasons to block the user from modifying the object in JavaScript if they want to do it. Immutability must be a hint and not enforced or it could block certain use cases.

[danielkhan]

SpanData is passed to the tracer and it's part of the spec as is immutability.
Further above I describe how mutation can lead to unexpected results and this has nothing to do with thread safety.
I think all these API design discussions should be done within the specification SIG.
I don't find it efficient to discuss that again for every language and platform.

I don't mind implementation details. The only strong opinion I have is that if there is a spec we should stick to it or request a change if we disagree.

[rochdev]

The problem with a restrictive spec is that it cannot work cross-language. The spec should only describe concepts and a loose reference API. Since the current iteration is only for Java, we should experiment with an API that works better for JavaScript and then we'll be able to change the spec accordingly.

Also, an API that is 100% theoretical never works. We need to prove that it works, similar to the current Java work.

[rochdev]

Further above I describe how mutation can lead to unexpected results and this has nothing to do with thread safety.

It can also prevent vendors to do certain things that they need. I think the idea is that APM vendors will be able to use the project implementation. If we end up needing to reimplement everything because of limitations that were added on purpose, then the value of OpenTelemetry becomes null. We can document that this should not be changed at a certain point in the lifecycle (mostly for users), but it should not be completely blocked.

[bg451]

I'm not a fan of SpanData as it adds a large API to an already large surface area. I have an RFC in the works to propose an alternative, but I'd like to give a short explanation here to hopefully get y'all thinking about it.

The primary use case around SpanData comes from the desire to construct and report out of band spans, meaning that you're creating "custom" spans for an operation you don't own. A good example of this is a program that takes in structured logs that contain correlation IDs and a duration (e.g. from splunk) and converts them a span for your tracing system. Another example is running a sidecar on an HAProxy machine, tailing the request logs, and creating spans.

Because you cannot set manually set the start and end timestamp with the current span API, and because you'd want as much span information as possible for the sampler, SpanData was created (I think). I'd like to propose getting rid of SpanData and tracer.recordSpanData by allowing startSpan() and span.finish() to accept span options, similar to OpenTracing. So for startSpan, you can have withTags, withStartTimestamp, withResources, etc. and for finish() you could have withEndTimestamp, withEvents, withLogs, etc. There's probably some more nuance to the sampler API than I currently understand, but I believe this would meet the requirements for out of band reporting.

Anyway, I'll look this PR according to the current spec. Would be more than happy to discuss further or give example code.

[rochdev]

I'm not a fan of SpanData as it adds a large API to an already large surface area.

Definitely agree. I proposed an alternative to most classes of the project here as well. In general, I think the OpenTracing API was enough for the most part. We even implemented our tracer 100% using only the OpenTracing API. I don't understand why all these new classes and limitations are being added, which will just get in the way of APM vendors. The API needs some serious KISS principle review.

[mayurkale22]

I see there are some discussions going about removing recordSpanData from the Tracer-API open-telemetry/opentelemetry-specification#71. I feel like we should hold this PR and leave out recordSpanData from the Tracer-API until we arrived at a conclusion. In fact, this is not a blocker for Tracer-API, I would add TODO in API to keep track later.

@danielkhan WDYT?

[draffensperger]

I know that @rochdev talked about the need to generate spans from existing measurement metadata as is the case with Apollo tracing. That's also a use case in the browser where we have entries from the Resource Timing API that we want to turn into spans.

I like the idea of just having a Span class that allows you to set the start/end times, which seems like it could address the case of creating spans after the fact without needing a new class for that case.

Basically what @bg451 said above! (Just catching up on this thread)

[danielkhan]

I see there are some discussions going about removing recordSpanData from the Tracer-API open-telemetry/opentelemetry-specification#71. I feel like we should hold this PR and leave out recordSpanData from the Tracer-API until we arrived at a conclusion. In fact, this is not a blocker for Tracer-API, I would add TODO in API to keep track later.

@danielkhan WDYT?

I will hold back and do a PR for the rest once I can merge TimedEvent.

[bg451]

Closing as SpanData has been removed from the specification in open-telemetry/opentelemetry-specification#215