Skip to content

Commit

Permalink
"Stand-alone event format" instead of "in-memory format" (#538)
Browse files Browse the repository at this point in the history
* Changed wording in the description of extensions from "in-memory" format
to "stand-alone event format" to better reflect the recent terminology
changes in the spec.

Signed-off-by: Klaus Deissner <klaus.deissner@sap.com>

* Removed sections about in-memory formats

Signed-off-by: Klaus Deissner <klaus.deissner@sap.com>

* Line length

Signed-off-by: Klaus Deissner <klaus.deissner@sap.com>

* Formatting

Signed-off-by: Klaus Deissner <klaus.deissner@sap.com>
  • Loading branch information
deissnerk authored and Doug Davis committed Oct 17, 2019
1 parent b330f0e commit 8e9ec41
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 58 deletions.
19 changes: 5 additions & 14 deletions documented-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,11 @@ Support for any extension is OPTIONAL. When an extension definition uses
[RFC 2199](https://www.ietf.org/rfc/rfc2119.txt) keywords (e.g. MUST, SHOULD,
MAY), this usage only applies to events that use the extension.

Extensions always follow a common placement strategy for in-memory formats (e.g.
[JSON](json-format.md), XML) that are decided by those
representations. Protocol bindings (e.g. [HTTP](http-protocol-binding.md),
[MQTT](mqtt-protocol-binding.md), [AMPQ](amqp-protocol-binding.md),
[NATS](nats-protocol-binding.md)) provide default placement for extensions, but
an extension MAY require special secondary representation when transported (e.g. tracing
standards that require specific headers). Extension authors SHOULD only require
special representation in protocol bindings where extensions integrate with
pre-existing specs; extensions with custom protocol bindings are much more
likely to be dropped by middleware that does not understand the extension.

As a convention, extensions of scalar types (e.g. `String`, `Binary`,
`URI-reference`, `Number`) document their `Value` and structured types document
their `Attributes`.
Extensions attributes, while not defined by the core CloudEvents specifications,
MUST follow the same serialization rules as defined by the format and protocol
binding specifications. See
[Extension Context Attributes](spec.md#extension-context-attributes) for more
information.

## Known Extensions

Expand Down
13 changes: 3 additions & 10 deletions extensions/distributed-tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,7 @@ Prometheus are built.
- Constraints
- OPTIONAL

## Encoding

### In-memory formats

The Distributed Tracing extension uses the key `distributedtracing` for
in-memory formats

### HTTP
## HTTP encoding

To integrate with existing tracing libraries, the Distributed Tracing attributes
MUST be encoded over HTTP(S) as headers. E.g.
Expand All @@ -46,10 +39,10 @@ CURL -X POST example/webhook.json \
## Conflicts
Since this extension defines secondary, special, seialization that differs
Since this extension defines secondary, special, serialization that differs
from other CloudEvents attributes, it is possible that the values of these two
could differ by the time the event is received at a destination. In those
cases, the serialization that followed the "general CloudEvents serialization
rules" MUST be used as the CloudEvents attribute. The other, secodary,
rules" MUST be used as the CloudEvents attribute. The other, secondary,
mapping MAY be picked-up and offered to the receiving application as
"additional" metadata.
30 changes: 8 additions & 22 deletions extensions/partitioning.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
# Partitioning extension

This extension defines an attribute for use by message brokers and their
clients that support partitioning of events, typically for the purpose of
scaling.
This extension defines an attribute for use by message brokers and their clients
that support partitioning of events, typically for the purpose of scaling.

Often in large scale systems, during times of heavy load, events being received need to be
partitioned into multiple buckets so that each bucket can be separately processed in order
for the system to manage the incoming load. A partitioning key can be used to determine
which bucket each event goes into. The entity sending the events can ensure that events
that need to be placed into the same bucket are done so by using the same partition key on
those events.
Often in large scale systems, during times of heavy load, events being received
need to be partitioned into multiple buckets so that each bucket can be
separately processed in order for the system to manage the incoming load. A
partitioning key can be used to determine which bucket each event goes into. The
entity sending the events can ensure that events that need to be placed into the
same bucket are done so by using the same partition key on those events.

## Attributes

Expand All @@ -27,16 +26,3 @@ those events.
* Constraints:
* REQUIRED
* MUST be a non-empty string

## Encoding

### In-memory formats

The partitionkey attribute extension uses the key `partitionkey` for
in-memory formats.

### Protocol format

The Partitioning extension does not customize any protocol binding's storage for
extensions.

13 changes: 1 addition & 12 deletions extensions/sampled-rate.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,4 @@ they impose additional sampling.
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.

### Protocol bindings

The Sampling extension does not customize any protocol binding's storage for
extensions.
- The rate MUST be greater than zero.

0 comments on commit 8e9ec41

Please sign in to comment.