diff --git a/extensions.md b/extensions.md index 0e0ede1f9..485953dc1 100644 --- a/extensions.md +++ b/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) \ No newline at end of file +## Known Extensions + +* [Distributed Tracing](extensions/distributed-tracing.md) +* [Sampling](extensions/sampled-rate.md) diff --git a/extensions/sampled-rate.md b/extensions/sampled-rate.md new file mode 100644 index 000000000..4a96f0aa5 --- /dev/null +++ b/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. + diff --git a/spec.md b/spec.md index a7346981a..d6760ae9b 100644 --- a/spec.md +++ b/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.