Add sampling extension. (#243)

* Add sampling extension.

This pull request supercedes #76 and builds upon #242.

Per agreement at the f2f meeting 2018-06-15, this will be ratified
as an extension but not currently as part of the core spec. The
early inclusion of the spec and the ability for side-cars to impose
sampling early in the pipeline make it reasonable to start with
this as an extension.

I know the original author hoped to make this a core feature, though
there are two upsides:
1. Due to other decisions on 2018-06-15, this will have zero impact
   on JSON encoding (but will in Proto and may in SDKs)
2. Extensions now get a whole document. This lets us pitch sampling
   in more detail.

Necessary additional changes:
* Added `Integer` to our type system
* Added convention for how scalar extensions should be documented.
  I'm not really excited about this proposal so others are welcome.

Special thanks to @maplebed for kicking this effort off.

Signed-off-by: Thomas Bouldin <[email protected]>

* PR feedback; also add conttent to extensions.md

Signed-off-by: Thomas Bouldin <[email protected]>

* @douglin doesn't like the world 'may' 😉

Signed-off-by: Thomas Bouldin <[email protected]>

* Add 'e.g.' to list of scalar types in conventions

Signed-off-by: Thomas Bouldin <[email protected]>

extensions.md

@@ -31,8 +31,17 @@ decided by those representations. Transport bindings (e.g.
 [AMPQ](amqp-transport-binding.md), [NATS](nats-transport-binding.md)) provide
 default placement for extensions, but an extension MAY require special
 representation when transported (e.g. tracing standards that require
-specific headers).
+specific headers). Extension authors SHOULD only require special
+representation in transport bindings where extensions integrate with
+pre-existing specs; extensions with custom transport bindings are much
+more likely to be dropped by middleware that does not understand the
+extension.
 
-## Documented Extensions
+As a convention, extensions of scalar types (e.g. `String`, `Binary`, `URI`,
+`Number`) document their `Value` and structured types document their 
+`Attributes`.
 
-* [Distributed Tracing](extensions/distributed-tracing.md)
+## Known Extensions
+
+* [Distributed Tracing](extensions/distributed-tracing.md)
+* [Sampling](extensions/sampled-rate.md)

extensions/sampled-rate.md

@@ -0,0 +1,39 @@
+# Sampling extension
+
+There are many cases in an Event's life when a system (either the system
+creating the event or a system transporting the event) might wish to only emit
+a portion of the events that actually happened. In a high throughput system
+where creating the event is costly, a system might wish to only create an event
+for 1/100 of the times that something happened. Additionally, during the
+transmission of an event from the source to the eventual recipient, any step
+along the way might choose to only pass along a fraction of the events it
+receives.
+
+In order for the system receiving the event to understand what is actually
+happening in the system that generated the event, information about how many
+similar events happened would need to be included in the event itself. This
+field provides a place for a system generating an event to indicate that the
+emitted event represents a given number of other similar events. It also
+provides a place for intermediary transport systems to modify the event when
+they impose additional sampling.
+
+## Value
+
+* Type: `Integer`
+* Description: The rate at which this event has already been sampled. Represents
+  the number of similar events that happened but were not sent plus this event.
+  For example, if a system sees 30 occurrences and emits a single event, `rate`
+  would be 30 (29 not sent and 1 sent).
+  A value of `1` is the equivalent of this extension not being used at all.
+* Constraints
+  * The rate MUST be greater than zero.
+
+## Encoding
+
+### In-memory formats
+The Sampling extension uses the key `sampledRate` for in-memory formats.
+
+### Transport bindings
+The Sampling extension does not customize any transport binding's storage
+for extensions.
+

spec.md

@@ -107,15 +107,16 @@ platform/vendor specific protocols (AWS Kinesis, Azure Event Grid).
 
 The following abstract data types are available for use in attributes.
 
+- `Integer` - A 32-bit whole number.
 - `String` - Sequence of printable Unicode characters.
 - `Binary` - Sequence of bytes.
-- `Map` - `String`-indexed dictionary of `Object`-typed values
-- `Object` - Either a `String`, or a `Binary`, or a `Map`
+- `Map` - `String`-indexed dictionary of `Object`-typed values.
+- `Object` - Either a `String`, or a `Binary`, or a `Map`, or an `Integer`.
 - `URI` - String expression conforming to `URI-reference`
   as defined in
   [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1).
 - `Timestamp` - String expression as defined in
-  [RFC 3339](https://tools.ietf.org/html/rfc3339)
+  [RFC 3339](https://tools.ietf.org/html/rfc3339).
 
 This specification does not define numeric or logical types.