Add Tracer operations specs. (#105)

* Add Tracer operations specs.

Fixes #38.

* recordSpanData should be async.

* Fix typos.

* Fix review comments.

* Fix another typo.

Co-Authored-By: Mayur Kale <mayurkale@google.com>

Author: 2 people

specification/tracing-api.md

@@ -16,7 +16,62 @@ TODO: How tracer can be constructed? https://github.com/open-telemetry/opentelem
 
 ### Tracer operations
 
-TODO: Tracing operations. https://github.com/open-telemetry/opentelemetry-specification/issues/38
+#### `GetCurrentSpan`: returns the current Span from the current context.
+
+There should be no parameter.
+
+Returns the default `Span` that does nothing and has an invalid `SpanContext` if no
+`Span` is associated with the current context, otherwise the current `Span` from the context.
+
+#### `WithSpan`: enters the scope of code where the given `Span` is in the current context.
+
+Required parameters:
+
+- The `Span` to be set to the current context.
+
+Returns an object that defines a scope where the given `Span` will be set to the current context.
+
+The scope is exited and previous state should be restored when the returned object is closed.
+
+#### `SpanBuilder`: returns a `SpanBuilder` to create and start a new `Span`.
+
+Required parameters:
+
+- Name of the span.
+
+Returns a `SpanBuilder` to create and start a new `Span`.
+
+#### `RecordSpanData`: records a `SpanData`.
+
+Required parameters:
+
+- `SpanData` to be reported to all exporters.
+
+This API allows to send a pre-populated span object to the exporter.
+Sampling and recording decisions as well as other collection optimizations are a
+responsibility of a caller.
+
+Note, the `SpanContext` object in the span population with
+the values that will allow correlation of telemetry is also a caller responsibility.
+
+This API should be non-blocking.
+
+#### `GetBinaryFormat`: returns the binary format interface which can serialize/deserialize `Span`s.
+
+There should be no parameter.
+
+Returns the binary format for this implementation. If no implementation is provided
+then no-op implementation will be used.
+
+#### `GetHttpTextFormat`: returns the HTTP text format interface which can inject/extract `Span`s.
+
+There should be no parameter.
+
+Returns the HTTP text format for this implementation. If no implementation is provided
+then no-op implementation will be used.
+
+Usually this will be the W3C Trace Context as the HTTP text format. For more details, see
+[trace-context](https://github.com/w3c/trace-context).
 
 ## Span
 
@@ -50,14 +105,14 @@ recording status, none of the below may be called after the `Span` is finished.
 
 #### `GetContext`: retrieve the `Span`s `SpanContext`
 
-There should be no parameters.
+There should be no parameter.
 
 **Returns** the `SpanContext` for the given `Span`. The returned value may be
 used even after the `Span` is finished.
 
 #### `IsRecordingEvents`: returns the flag whether this span will be recorded
 
-There should be no parameters.
+There should be no parameter.
 
 Returns true if this `Span` is active and recording information like events with
 the `AddEvent` operation and attributes using `SetAttributes`.
@@ -136,7 +191,7 @@ with the `Span`).
 Call to `End` of a `Span` MUST not have any effects on child spans. Those may
 still be running and can be ended later.
 
-There MUST be no parameters.
+There MUST be no parameter.
 
 This API MUST be non-blocking.