Add specs on DistributedContext and propagation. (open-telemetry#97)

* Add specs on DistributedContext and propagation.

* Clarify DistributedContext only includes entries.

* Fix typos.

* Apply suggestions.

* Copy the description to terminology.

* Example on propagation across boundaries.

specification/distributedcontext-api.md

@@ -2,6 +2,14 @@
 An `Entry` is used to label anything that is associated
 with a specific operation, such as an HTTP request.
 
+`DistributedContext` is an abstract data type that represents collection of entries.
+Each key of `DistributedContext` is associated with exactly one value. `DistributedContext` is serializable,
+to facilitate propagating it not only inside the process but also across process boundaries.
+`DistributedContext` is used to annotate telemetry with the name:value pair `Entry`.
+Those values can be used to add dimension to the metric or additional contest properties to logs and traces.
+
+`DistributedContext` is a recommended name but languages can have more language-specific names like `dctx`.
+
 # Entry
 An `Entry` consists of EntryMetadata, EntryKey, and EntryValue.
 
@@ -129,3 +137,74 @@ Enter Scope 1
    Current Entries E1=V1/M1, E2=V2/M2  <== E2 is restored.
 Close Scope 1
 ``` 
+
+# DistributedContext
+
+## GetIterator
+
+Returns an iterator over the entries in this `DistributedContext`.
+The order of entries is not significant. The iterator MUST not modify the underlying collection of
+entries in this `DistributedContext`.
+
+## GetEntryValue
+
+Returns the `EntryValue` associated with the given `EntryKey`, or null if the given `EntryKey`
+is not present.
+
+Required parameter:
+
+`EntryKey` entry key to return the value for.
+
+## Limits
+Combined size of all entries should not exceed 8192 bytes before encoding.
+The size restriction applies to the deserialized entries so that the set of decoded
+ `DistributedContext`s is independent of the encoding format.
+
+## DistributedContext Propagation
+`DistributedContext` may be propagated across process boundaries or across any arbitrary boundaries
+(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons.
+For example, one may propagate 'project-id' Entry across all micro-services to break down metrics
+by 'project-id'. Not all entries in a `DistributedContext` should be propagated and not all entries in a `DistributedContext`
+should be accepted from a remote peer. Hence, `DistributedContext` propagator must allow specifying an optional
+list of ordered `EntryPropagationFilter`s for receiving entries or for forwarding entries or for both. 
+An `EntryPropagationFilter` list for receiving MAY be different than that for forwarding.
+
+If no filter is specified for receiving then all entries are received. 
+If no filter is specified for forwarding then all entries are forwarded except those that have `EntryTTL` of 0.
+
+### EntryPropagationFilter
+Entry Propagation Filter consists of an action (`EntryPropagationFilterAction`) and a condition 
+(`EntryPropagationFilterMatchOperator` and `EntryPropagationFilterMatchString`). An `EntryKey` 
+is evaluated against condition of each `EntryPropagationFilter` in order. If the condition is evaluated
+to true then action is taken according to `EntryPropagationFilterAction` and filter processing is stopped.
+If the condition is evaluated to false then the `EntryKey` is processed against next `EntryPropagationFilter`
+in the ordered list. If none of the condition is evaluated to true then the default
+action is **Exclude**.
+
+#### EntryPropagationFilterAction
+This is an interface. Implementation of this interface takes appropriate action on the `Entry` if the 
+condition (`EntryPropagationFitlerMatchOperator` and `EntryPropagationFilterMatchString`) is evaluated to true.
+At a minimum, `Exclude` and `Include` actions MUST be implemented.
+
+**Exclude**
+If the `EntryPropagationFilterAction` is Exclude then any `Entry` whose `EntryKey` evaluates to true 
+with the condition (`EntryPropagationFitlerMatchOperator` and `EntryPropagationFilterMatchString`)
+MUST be excluded.
+
+**Include**
+If the `EntryPropagationFilterAction` is Include then any `Entry` whose `EntryKey` evaluates to true 
+with the condition (`EntryPropagationFitlerMatchOperator  ` and `EntryPropagationFilterMatchString`)
+MUST be included. 
+
+#### EntryPropagationFilterMatchOperator
+
+| Operator | Description |
+|----------|-------------|
+| EQUAL | The condition is evaluated to true if `EntryKey` is exactly same as `EntryPropagationFilterMatchString` |
+| NOTEQUAL | The condition is evaluated to true if `EntryKey` is NOT exactly same as `EntryPropagationFilterMatchString` |
+| HAS_PREFIX | The condition is evaluated to true if `EntryKey` begins with `EntryPropagationFilterMatchString` |
+
+#### EntryPropagationFilterMatchString
+It is a string to compare against EntryKey using `EntryPropagationFilterMatchOperator` in order to 
+include or exclude an `Entry`.
+

terminology.md

@@ -108,6 +108,15 @@ TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemet
 
 ## DistributedContext
 
+**DistributedContext** is an abstract data type that represents collection of entries.
+Each key of **DistributedContext** is associated with exactly one value. **DistributedContext** is serializable,
+to facilitate propagating it not only inside the process but also across process boundaries.
+
+**DistributedContext** is used to annotate telemetry with the name:value pair **Entry**.
+Those values can be used to add dimension to the metric or additional contest properties to logs and traces.
+
+**DistributedContext** is a recommended name but languages can have more language-specific names like **dctx**.
+
 ### Entry
 
 An **Entry** is used to label anything that is associated  with a specific operation,