From 8e9ec4154bc94c79c52bc63a9a867e5290744e3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Klaus=20Dei=C3=9Fner?= Date: Thu, 17 Oct 2019 20:57:10 +0200 Subject: [PATCH] "Stand-alone event format" instead of "in-memory format" (#538) * 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 * Removed sections about in-memory formats Signed-off-by: Klaus Deissner * Line length Signed-off-by: Klaus Deissner * Formatting Signed-off-by: Klaus Deissner --- documented-extensions.md | 19 +++++-------------- extensions/distributed-tracing.md | 13 +++---------- extensions/partitioning.md | 30 ++++++++---------------------- extensions/sampled-rate.md | 13 +------------ 4 files changed, 17 insertions(+), 58 deletions(-) diff --git a/documented-extensions.md b/documented-extensions.md index 8e2d76476..4772ac36e 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -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 diff --git a/extensions/distributed-tracing.md b/extensions/distributed-tracing.md index 44a627497..1cae490e7 100644 --- a/extensions/distributed-tracing.md +++ b/extensions/distributed-tracing.md @@ -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. @@ -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. diff --git a/extensions/partitioning.md b/extensions/partitioning.md index 67e3bf916..c7c866f4a 100644 --- a/extensions/partitioning.md +++ b/extensions/partitioning.md @@ -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 @@ -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. - diff --git a/extensions/sampled-rate.md b/extensions/sampled-rate.md index 6aeb74255..6af980057 100644 --- a/extensions/sampled-rate.md +++ b/extensions/sampled-rate.md @@ -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. \ No newline at end of file