Add details about sampling and minimal details about Span and TraceConfig. (#6)

* Add details about sampling and minimal details about Span and TraceConfig.

* Fix comments.

Author: Bogdan Drutu

README.md

@@ -4,6 +4,8 @@
 * For details about the library structured see [Namespace and Package](https://github.com/census-instrumentation/opencensus-specs/blob/master/NamespaceAndPackage.md)
 
 ## Trace Design
+* Trace API is described [here](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/README.md)
+
 * Data model is defined [here](https://github.com/census-instrumentation/opencensus-proto/blob/master/trace/trace.proto)
 
 ## Tags Design

trace/README.md

@@ -0,0 +1,12 @@
+# OpenCensus Library Trace API
+This document serves to document the "look and feel" of the open source trace API's. It describes
+the key types (classes, structures, etc.) and functions (methods, etc.). This document uses 
+terminology (MUST, SHOULD, etc) from [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+## Main APIs
+* [Span API]()
+* [TraceConfig API]()
+
+## Utils
+* [Sampling logic](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace
+/Sampling.md)

trace/Sampling.md

@@ -0,0 +1,35 @@
+# Sampling
+
+This document is about the sampling bit, sampling decision, samplers and how and when does 
+OpenCensus sample traces. A sampled traces is a traces that gets exported via the configured
+exporters.
+
+## Sampling Bit (propagated via TraceOptions)
+
+Sampling bit is always set only at the start of a Span, and is using a `Sampler`
+
+### What kind of samplers does OpenCensus support?
+* `AlwaysSample` - sampler that always makes a "yes" decision every time.
+* `NeverSample` - sampler that always makes a "no" decision every time.
+* `Probability` - sampler that tries to uniformly sample traces with a given probability. When 
+applied to a child `Span` of a **sampled** parent `Span` then it keeps the sampling decision.
+
+### How can users control the Sampler that is used for sampling?
+There are 2 ways to control the `Sampler` used when the library does sampling:
+* Controlling the global default `Sampler` via [TraceConfig](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/TraceConfig.md).
+* Pass a specific `Sampler` when start the [Span](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Span.md)
+(a.k.a. "span-scoped").
+  * For example `AlwaysSample` and `NeverSample` can be used to implement request-specific 
+  decisions such as those based on http paths.
+
+### When does OpenCensus sample traces?
+The OpenCensus library does sampling based on the following rules:
+1. If the span is a root `Span` then a `Sampler` will be used to make the sampling decision:
+   * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision.
+   * Else use the global default `Sampler` to determine the sampling decision.
+2. If the span is a child of a remote `Span` the sampling decision will be:
+   * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision.
+   * Else use the global default `Sampler` to determine the sampling decision.
+2. If the span is a child of a local `Span` the sampling decision will be:
+   * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision.
+   * Else keep the sampling from the parent.

trace/Span.md

@@ -0,0 +1,32 @@
+# Span API
+
+This class represents a Span. A span contains a SpanContext and  allows users to record 
+tracing events based on the data model defined [here](https://github.com/census-instrumentation/opencensus-proto/blob/master/trace/trace.proto).
+All Span implementations MUST not allow users to read the recorded data, 
+
+## Span structure
+
+### SpanContext
+Represents all the information that MUST be propagated to child Spans and across process boundaries.
+A span context contains the tracing identifiers and the options that are propagated from parent 
+to child Spans.
+
+#### TraceId 
+Is the identifier for a trace. It is worldwide unique with practically sufficient 
+probability by being made as 16 randomly generated bytes. TraceId is used to group all spans for 
+a specific trace together across all processes.
+
+#### SpanId 
+Is the identifier for a span. It is globally unique with practically sufficient probability by 
+being made as 8 randomly generated bytes. When passed to a child Span this identifier becomes the
+parent span id for the child Span.
+
+#### TraceOptions 
+Represents the options for a trace. It is represented as 1 byte (bitmap).
+
+##### Supported bits
+* Sampling bit -  Bit to represent whether trace is sampled or not (mask `0x1`).
+
+## Span creation API
+
+TODO(bdrutu): Add details here.

trace/TraceConfig.md

@@ -0,0 +1,16 @@
+# TraceConfig API
+
+Global configuration of the trace service. This allows users to change configs for the default
+sampler, maximum events to be kept, etc.
+
+## TraceParams
+Represents the set of parameters that users can control 
+* Default `Sampler` - used when creating a Span if no specific sampler is given.
+
+TODO(bdrutu): Define the rest of the params.
+
+## API Summary
+* Permanently update the active TraceParams.
+* Temporary update the active TraceParams. This API allows changing of the active params for a 
+certain period of time. No more than one active temporary update can exist at any moment.
+* Get current active TraceParams.