Add interface for a trace recorder

[rnburn]

Sets up the interface for a recorder that receives finished spans.

In this design, spans create a Recordable object when they're started and use it to build up their data representation.

A key goal of the design is to allow for performant implementations that avoid the cost of translating a "Span Data" like object into the exported formats.

A common SpanData implementation is still possible and fits into easly the Recordable concept.

class SpanData final : public Recordable {
  // provide accessor interface that can be used for translation
  nostd::string_view name() const noexcept { return name_; }
   // implement recordable methods
 void UpdateName(nostd::string_view name) noexcept override {
     //...
 }
 ...
 private:
   std::string name_;
};

So SpanData-like exporters are still possible, but more efficient implementations can derive from the Recordable class and write to the exported format directly.

Also, this design can support multiple formats and Recorders with composite types.

class CompositeRecordable final : public Recordable {
 public:
  void UpdateName(nostd::string_view name) noexcept override {
     for(auto& recordable : recordables_) {
        recordable->UpdateName(name);
     }
  }
 private:
   std::vector<std::unique_ptr<Recordable>> recordables_;
}

[g-easy]

Nice.

[g-easy]

A key goal of the design is to allow for performant implementations that avoid the cost of translating a "Span Data" like object into the exported formats.

This is part of the SDK, not the API, right?

Really what this means is that the default SDK implementation that we provide will choose to do things via the Recorder approach?

[rnburn]

This is part of the SDK, not the API, right?

Yes, SDK only

Really what this means is that the default SDK implementation that we provide will choose to do things via the Recorder approach?

Right, but I wouldn't say the recorder approach imposes many limitations. It really only says that a Span builds up a Recordable object that gets consumed by a Recorder.

[pyohannes]

While SpanData-like exporters are still possible, more efficient implementations can derive from the Recordable class and write to the exported format directly.

One limitation I see with this Recorder approach is, that there can only be one Recorder per Tracer. However, one Tracer can have multiple processors/exporters (per spec).

[g-easy]

one Recorder per Tracer

But the Recorder can fan out to many Exporters without a problem, right?

[rnburn]

But the Recorder can fan out to many Exporters without a problem, right?

For sure. You can have both a fanning Recordable that builds up multiple data formats and a fanning Recorder that directs the data formats to multiple span processors.

[g-easy]

Implies the recorder passed to the constructor can't be nullptr, right? Is this worth documenting?

[rnburn]

Yes, I added a note.

[rnburn]

@pyohannes - I added a composite example to the description.

[rnburn]

@reyang @pyohannes - could you review?

[reyang]

@reyang @pyohannes - could you review?

Sure, on it now!

[reyang]

I wonder if we will have similar Recordable class for metrics and logs moving forward.

[rnburn]

I think that would make sense. I find it useful to have interfaces that just capture events and don't mandate an accessor interface or maintaining data in a structured form.

[reyang]

What's the point of using a mutex here?
I guess this would only make sense when the caller has knowledge about the mutex, otherwise by the time the caller received the return value, it might not be the current status.

[rnburn]

I suppose the return value might not be accurate if you have other threads simultaneously ending the span. But it would be undefined behavior without it and this will at least prevent TSAN from flagging it as an error.

[pyohannes]

Do you think that we need to represent parenting on this level? Given this interface, I don't see how an exporter can determine a parent span or recordable.

[rnburn]

Not all the methods are filled in (because we don't have all the types and methods in the api yet).

But there will be some kind of SpanContext type with a corresponding, SetSpanContext or something similar as well as AddLink methods. Those would pass the parenting information.

[pyohannes]

Is there a reason for using std::unique_ptr instead of nonstd::unique_ptr in this interface?

[rnburn]

I was limiting nostd::unique_ptr to the places where we need a stable ABI that could cross DSOs.

I don't know that are plans to support dynamically loadable Recorders. I feel like we should try to limit the points where we support plug-ability to avoid confusion and we already have two that we've discussed targeting (i.e. Tracer plugins and Exporter plugins)

[g-easy]

I think Recorder should be an implementation detail of the SDK.

[reyang]

LGTM, I have minor concerns regarding whether we will need it for logs and metrics, but that can be addressed later.