span operations API (open-telemetry#29)

* span operations API

* fixed TBD on span

* fixed a link

* addressed Bogdan's feedback

* fixed optionality of attributes

* Update tracing-api.md

specification/README.md

@@ -0,0 +1,8 @@
+# Cross language specification
+
+This documentation serves to document the "look and feel" of the API. It
+describes the key types and the overall behavior.
+
+Main APIs:
+
+- [Tracing API](tracing-api.md).

specification/tracing-api.md

@@ -0,0 +1,137 @@
+# Tracing API
+
+Tracing API consist of a few main classes:
+
+- `Tracer` is used for all operations. See [Tracer](#tracer) section.
+- `Span` is a mutable object storing information about the current operation
+   execution. See [Span](#span) section.
+- `SpanData` is an immutable object that is used to report out-of-band completed
+  spans. See [SpanData](#spandata) section.
+
+## Tracer
+
+### Obtaining a tracer
+
+TODO: How tracer can be constructed? https://github.com/open-telemetry/opentelemetry-specification/issues/39
+
+### Tracer operations
+
+TODO: Tracing operations. https://github.com/open-telemetry/opentelemetry-specification/issues/38
+
+## Span
+
+Span represents a single operation within a trace. Spans can be nested to form a
+trace tree. Often, a trace contains a root span that describes the end-to-end
+latency and, optionally, one or more sub-spans for its sub-operations.
+
+Once Span [is created](#span-creation) - Span operations can be used to add
+additional properties to it like attributes, links, events, name and resulting
+status. Span cannot be used to retrieve these properties. This prevents the
+mis-use of spans as an in-process information propagation mechanism.
+
+The only two getters on span returns `SpanContext` and the flag on whether span
+will be recorded.
+
+### Span creation
+
+TODO: SpanBuilder API https://github.com/open-telemetry/opentelemetry-specification/issues/37
+
+### Span operations
+
+With the exception of the method to retrieve the `Span`'s `SpanContext` and
+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.
+
+**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.
+
+Returns true if this `Span` is active and recording information like events with
+the `AddEvent` operation and attributes using `SetAttributes`.
+
+### `SetAttribute`: set the `Span`'s attribute
+
+Required parameters
+
+- The attribute key, which must be a string.
+- The attribute value, which must be either a string, a boolean value, or a
+  numeric type.
+
+Note that the OpenTelemetry project documents certain ["standard
+attributes"](../semantic-conventions.md) that have prescribed semantic meanings.
+
+### `AddEvent`: add an `Event` to `Span`
+
+Required parameters:
+
+- Name of the event.
+
+Optional parameters:
+
+- One or more key:value pairs, where the keys must be strings and the values may
+  be string, booleans or numeric type.
+
+Note that the OpenTelemetry project documents certain ["standard event names and
+keys"](../semantic-conventions.md) which have prescribed semantic meanings.
+
+### `AddLink`: add a `Link` from this `Span` to another
+
+Adds a link to another `Span` from this `Span`. Linked `Span` can be from the
+same or different trace. See [Links description](../terminology.md#links-between-spans).
+
+Required parameters
+
+- `SpanContext` of the `Span` to link to
+
+Optional parameters
+
+- Map of attributes associated with this link. Attributes are key:value pairs
+  where hey is a string and value is one of string, boolean and numeric.
+
+### `SetStatus`: set the span result status
+
+Sets the `Status` to the `Span`. If used, this will override the default `Span`
+status. Default is `OK`.
+
+Only the value of the last call will be recorded, and implementations are free
+to ignore previous calls.
+
+Required parameters
+
+- New status for the span.
+
+#### `UpdateName`: overwrite the operation name
+
+Updates the `Span` name. Upon this update, any sampling behavior based on
+`Span` name will depend on the implementation.
+
+Required parameters:
+
+- The new **operation name**, which supersedes whatever was passed in when the
+  `Span` was started
+
+#### `End`: finish the `Span`
+
+There should be no parameters.
+
+### Span lifetime
+
+Span lifetime represents the process of recording the start and the end
+timestamps to the Span object:
+
+- The start time is recorded when the Span is created.
+- The end time needs to be recorded when the operation is ended.
+
+Start and end time as well as Event's timestamps MUST be recorded at a time of a
+calling of corresponding API and MUST not be passed as an argument. In order to
+record already completed span - [`SpanData`](#spandata) API HAVE TO be used.
+
+## SpanData
+
+TODO: SpanData operations https://github.com/open-telemetry/opentelemetry-specification/issues/35

work_in_progress/specification/README.md

@@ -139,48 +139,7 @@ Both injection and extraction rely on an extensible **format** parameter that di
 
 ### `Span`
 
-With the exception of the method to retrieve the `Span`'s `SpanContext`, none of the below may be called after the `Span` is finished.
-
-#### Retrieve the `Span`s `SpanContext`
-
-There should be no parameters.
-
-**Returns** the `SpanContext` for the given `Span`. The returned value may be used even after the `Span` is finished.
-
-#### Overwrite the operation name
-
-Required parameters
-
-- The new **operation name**, which supersedes whatever was passed in when the `Span` was started
-
-#### Finish the `Span`
-
-Optional parameters
-
-- An explicit **finish timestamp** for the `Span`; if omitted, the current walltime is used implicitly.
-
-With the exception of the method to retrieve a `Span`'s `SpanContext`, no method may be called on a `Span` instance after it's finished.
-
-#### Set a `Span` tag
-
-Required parameters
-
-- The tag key, which must be a string
-- The tag value, which must be either a string, a boolean value, or a numeric type
-
-Note that the OpenTracing project documents certain **["standard tags"](./semantic_conventions.md#span-tags-table)** that have prescribed semantic meanings.
-
-#### Log structured data
-
-Required parameters
-
-- One or more key:value pairs, where the keys must be strings and the values may have any type at all. Some OpenTracing implementations may handle more (or more of) certain log values than others.
-
-Optional parameters
-
-- An explicit timestamp. If specified, it must fall between the local start and finish time for the span.
-
-Note that the OpenTracing project documents certain **["standard log keys"](./semantic_conventions.md#log-fields-table)** which have prescribed semantic meanings.
+... moved to [specs](../../specification/tracing-api.md)...
 
 #### Set a **baggage** item
 

work_in_progress/specification/trace/README.md

@@ -1,6 +1,4 @@
 # OpenCensus Library Trace Package
-This documentation serves to document the "look and feel" of the open source tags package. It 
-describes the key types and the overall behavior.
 
 ## Main APIs
 * [Span](Span.md)

work_in_progress/specification/trace/Span.md

@@ -1,4 +1,5 @@
 # Span
+
 
 ... parts of this document moved to [terminology.md](../terminology.md) ...
 
@@ -40,12 +41,6 @@ Span is attached (immutable Context):
 * When attach/detach an already created Span the API MAY be called `WithSpan`.
 * When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`.
 
-### What is Span lifetime?
-Span lifetime represents the process of recording the start and the end timestamps to the Span 
-object:
-* The start time is recorded when the Span is created.
-* The end time needs to be recorded when the operation is ended.
-
 ### Why support Spans that are not attached to the Context?
 * Allow users to use the OpenCensus library without using a Context.
 * Allow users to have more control for the lifetime of the Span.