Add methods to Flush and Close a tracer

[rnburn]

No description provided.

[reyang]

Logically this change makes sense.
I have the following stepping back questions:

1. In the specification, it seems flush will be treated as a SpanProcessor feature rather than Tracer feature. Add flush interface to span processor opentelemetry-specification#370
2. The name FlushWithMicroseconds sounds weird to me. How about Flush(timeout_in_microseconds = INFINITE)?
3. The return value concerns me. There could be multiple scenarios:

• Flush succeeded, yeah!
• Flush timed out, we don't know if the other side received the data or not.
• Flush failed, and we know what has happened (e.g. the disk is full, so we return immediately for a file exporter; DNS resolution failure while we try to export to an HTTP endpoint).
• Flush failed, and we don't know what has happened (e.g. connection reset, the server side might or might not receive the data).
• Flush partially succeeded (e.g. some data in the buffer is too old and doesn't make sense to get exported - e.g. device scenario where a device wakes up after sleeping for months; we receive HTTP Partial Success from the ingestion service, that only part of the data has been accepted).

[rnburn]

1. In the specification, it seems flush will be treated as a SpanProcessor feature rather than Tracer feature. Add flush interface to span processor opentelemetry-specification#370

Tracer can forward to any attached SpanProcessors.

2. The name FlushWithMicroseconds sounds weird to me. How about Flush(timeout_in_microseconds = INFINITE)?

There are non-virtual Flush and Close functions. You call them with the C++11 chrono types (e.g. tracer->Flush(std::chrono::milliseconds{5}).)

FlushWithMicroseconds is to have a virtual function with a stable ABI -- I wouldn't expect most users to invoke it directly. (But I'm open to tweaking the naming).

3. The return value concerns me.

I'll remove the return value.

[reyang]

1. In the specification, it seems flush will be treated as a SpanProcessor feature rather than Tracer feature. open-telemetry/opentelemetry-specification#370

Tracer can forward to any attached SpanProcessors.

Do we want to get Tracer.Flush into the OpenTelemetry specification? In general what's our position on exposing additional APIs that are not spec'ed out?

[reyang]

The approach looks good to me.
I've put some stepping back questions for discussion.

[pyohannes]

Do we want to get Tracer.Flush into the OpenTelemetry specification? In general what's our position on exposing additional APIs that are not spec'ed out?

I have concerns about having those methods methods (particularly the Close method) on the API level. Those shouldn't block the merge, but I nevertheless want to express them.

As far as I understand, the API layer is strictly targeting instrumenters, while the SDK layer is targeting application operators. I think instrumenters aren't supposed to have the ability to close a tracer. If there's a Close method on the API level, an application operator using OT has to be aware that any (evil) OT-enabled library he's using might possible close the Tracer he has initialized.

I guess that's the reason why those methods aren't in the spec (and why they most likely will not make it into the spec).

[rnburn]

Applications need the ability to exit quickly.

We can't have a tracer implementation hang up an application while it blocks on a socket for an indefinite amount of time to send buffered spans to a collection point.

At the same time, some applications may want to make an effort to send buffered spans before they exit. The amount of time an application would be willing to wait will, of course, vary on the use case.

That's why something like Close is necessary. If you don't call Close, then an app should be able to exit immediately without waiting on a tracer. Otherwise, it can Close with a timeout to allow the tracer to cleanly stop.

[pyohannes]

Applications need the ability to exit quickly.

I 100% agree.

Thinking a bit more about this, I wonder it TracerProvider wouldn't be better candidate to have a Close method? If I understand correctly, a TracerProvider can return different Tracers (hence the library and version arguments to the Get method). To exit the application, one would need to close all tracers that are floating around.

[reyang]

FYI - there was a discussion in the OpenTelemetry specification around flush API design.
open-telemetry/opentelemetry-specification#351

[rnburn]

@reyang - sorry I missed the meeting. I added open-telemetry/opentelemetry-specification#351 (comment) to describe the Flush use-case.