From db519d622043eacb9c71c4b12a0e46d69cccf220 Mon Sep 17 00:00:00 2001 From: Yang Song Date: Mon, 10 Jun 2019 15:37:30 -0700 Subject: [PATCH] Add initial spec for DistributedContext.Entry (#73) * Add initial spec for DistributedContext.Entry * Remove WIP TagMap specs. * Add Entry related terminology. * Add description of supported operations and types. --- terminology.md | 18 +- work_in_progress/specification/tags/README.md | 6 - work_in_progress/specification/tags/TagMap.md | 189 ------------------ 3 files changed, 16 insertions(+), 197 deletions(-) delete mode 100644 work_in_progress/specification/tags/README.md delete mode 100644 work_in_progress/specification/tags/TagMap.md diff --git a/terminology.md b/terminology.md index 24ad3f410..2b95fb206 100644 --- a/terminology.md +++ b/terminology.md @@ -106,9 +106,23 @@ Trace instead of trusting incoming Trace context. TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemetry-specification/issues/45 -## Tags +## DistributedContext -TODO: Describe tags terminology https://github.com/open-telemetry/opentelemetry-specification/issues/46 +### Entry + +An **Entry** is used to label anything that is associated with a specific operation, +such as an HTTP request. It consists of **EntryKey**, **EntryValue** and **EntryMetadata**. + +- **EntryKey** is the name of the **Entry**. **EntryKey** along with **EntryValue** +can be used to aggregate and group stats, annotate traces and logs, etc. **EntryKey** is +a string that contains only printable ASCII (codes between 32 and 126 inclusive) and with +a length greater than zero and less than 256. +- **EntryValue** is a string that contains only printable ASCII (codes between 32 and 126). +- **EntryMetadata** contains properties associated with an **Entry**. +For now only the property **EntryTTL** is defined. +- **EntryTTL** is an integer that represents number of hops an entry can propagate. +Anytime a sender serializes an entry, sends it over the wire and receiver unserializes +the entry then the entry is considered to have travelled one hop. ## Resources diff --git a/work_in_progress/specification/tags/README.md b/work_in_progress/specification/tags/README.md deleted file mode 100644 index 5e53c40b1..000000000 --- a/work_in_progress/specification/tags/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# OpenCensus Library Tags Package -This documentation serves to document the "look and feel" of the open source tags package. It -describes the key types and the overall behavior. - -## Main APIs -* [TagMap](TagMap.md) diff --git a/work_in_progress/specification/tags/TagMap.md b/work_in_progress/specification/tags/TagMap.md deleted file mode 100644 index 8435f4abd..000000000 --- a/work_in_progress/specification/tags/TagMap.md +++ /dev/null @@ -1,189 +0,0 @@ -# Summary -A `Tag` is used to label anything that is associated -with a specific operation, such as an HTTP request. These `Tag`s are used to -aggregate measurements in a [`View`](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/DataAggregation.md#view) -according to unique value of the `Tag`s. The `Tag`s can also be used to filter (include/exclude) -measurements in a `View`. `Tag`s can further be used for logging and tracing. - -# Tag -A `Tag` consists of TagMetadata, TagKey, and TagValue. - -## TagKey - -`TagKey` is the name of the Tag. TagKey along with `TagValue` is used to aggregate -and group stats, annotate traces and logs. - -**Restrictions** -- Must contain only printable ASCII (codes between 32 and 126 inclusive) -- Must have length greater than zero and less than 256. -- Must not be empty. - -## TagValue - -`TagValue` is a string. It MUST contain only printable ASCII (codes between -32 and 126) - -## TagMetadata - -`TagMetadata` contains properties associated with a `Tag`. For now only the property `TagTTL` -is defined. In future, additional properties may be added to address specific situations. - -A tag creator determines metadata of a tag it creates. - -### TagTTL - -`TagTTL` is an integer that represents number of hops a tag can propagate. Anytime a sender serializes a tag, -sends it over the wire and receiver unserializes the tag then the tag is considered to have travelled one hop. -There could be one or more proxy(ies) between sender and receiver. Proxies are treated as transparent -entities and they may not create additional hops. Every propagation implementation should support an option -`decrementTTL` (default set to true) that allows proxies to set it to false. - -**For now, ONLY special values (0 and -1) are supported.** - -#### Special Values -- **NO_PROPAGATION (0)**: Tag with `TagTTL` value of zero is considered to have local scope and - is used within the process it created. - -- **UNLIMITED_PROPAGATION (-1)**: A Tag with `TagTTL` value of -1 can propagate unlimited hops. - However, it is still subject to outgoing and incoming (on remote side) filter criteria. - See `TagPropagationFilter` in [Tag Propagation](#Tag Propagation). `TagTTL` value of -1 - is typical used to represent a request, processing of which may span multiple entities. - -#### Example for TagTTL > 0 -On a server side typically there is no information about the caller besides ip/port, -but in every process there is a notion of "service_name" tag that is added as a "caller" tag before -serialization when a RPC/HTTP call is made. For the "caller" tag, desirable `TagTTL` value is 1. - -Note that TagTTL value of 1 is not supported at this time. The example is listed here simply to -show a possible use case for TagTTL > 0. - -### Processing at Receiver and Sender -For now, limited processing is required on Sender and Receiver. However, for the sake of -completeness, future processing requirement is also listed here. These requirements are marked with -"**(future)**". - -This processing is done as part of tag propagator. - -#### At Receiver -Upon receiving a tag from remote entity a tag extractor - -- MUST decrement the value of `TagTTL` by one if it is greater than zero. **(future)** -- MUST treat the value of `TagTTL` as -1 if it is not present. -- MUST discard the `Tag` for any other value of `TagTTL`. **(future)** - -#### At Sender -Upon preparing to send a tag to a remote entity a tag injector -- MUST send the tag AND include `TagTTL` if its value is greater than 0. **(future)** -- MUST send the tag without 'TagTTL' if its value is -1. Absence of TagTTL on the wire is treated as having TagTTL of -1. - This is to optimize on-the-wire representation of common case. -- MUST not send the tag if the value of `TagTTL` is 0. - -A tag accepted for sending/receiving based on `TagTTL` value could still be excluded from sending/receiving based on -`TagPropagationFilter`. - -## Tag Conflict Resolution -If a new tag conflicts with an existing tag then the new tag takes precedence. Entire `Tag` along -with `TagValue` and `TagMetadata` is replaced by the most recent tag (regardless of it is locally -generated or received from a remote peer). Replacement is limited to a scope in which the -conflict arises. When the scope is closed the orignal value and metadata prior to the conflict is restored. -For example, -``` -T# - Tag keys -V# - Tag Values -M# - Tag Metadata - -Enter Scope 1 - Current Tags T1=V1/M1, T2=V2/M2 - Enter Scope 2 - Add Tags T3=V3/M3, T2=v4/M4 - Current Tags T1=V1/M1, T2=V4/M4, T3=V3/M3 <== Value/Metadata of T2 is replaced by V4/M4. - Close Scope 2 - Current Tags T1=V1/M1, T2=V2/M2 <== T2 is restored. -Close Scope 1 -``` - - -# TagMap -`TagMap` is an abstract data type that represents collection of tags. -i.e., each key is associated with exactly one value. `TagMap` is serializable, and it represents -all of the information that could be propagated inside the process and across process boundaries. -`TagMap` is a recommended name but languages can have more language specific name. - -## Limits -Combined size of all `Tag`s should not exceed 8192 bytes before encoding. -The size restriction applies to the deserialized tags so that the set of decoded - `TagMap`s is independent of the encoding format. - -## TagMap Propagation -`TagMap` may be propagated across process boundaries or across any arbitrary boundaries for various -reasons. For example, one may propagate 'project-id' Tag across all micro-services to break down metrics -by 'project-id'. Not all `Tag`s in a `TagMap` should be propagated and not all `Tag`s in a `TagMap` -should be accepted from a remote peer. Hence, `TagMap` propagator must allow specifying an optional -list of ordered `TagPropagationFilter`s for receiving `Tag`s or for forwarding `Tag`s or for both. -A `TagPropagationFilter` list for receiving MAY be different then that for forwarding. - -If no filter is specified for receiving then all `Tag`s are received. -If no filter is specified for forwarding then all `Tag`s are forwarded except those that have `TagTTL` of 0. - -### TagPropagationFilter -Tag Propagation Filter consists of action (`TagPropagationFilterAction`) and condition -(`TagPropagationFilterMatchOperator` and `TagPropagationFilterMatchString`). A `TagKey` -is evaluated against condition of each `TagPropagationFilter` in order. If the condition is evaluated -to true then action is taken according to `TagPropagationFilterAction` and filter processing is stopped. -If the condition is evaluated to false then the `TagKey` is processed against next `TagPropagationFilter` -in the ordered list. If none of the condition is evaluated to true then the default -action is **Exclude**. - -#### TagPropagationFilterAction -This is an interface. Implementation of this interface takes appropriate action on the `Tag` if the -condition (`TagPropagationFitlerMatchOperator` and `TagPropagationFilterMatchString`) is evaluated to true. -At a minimum, `Exclude` and `Include` actions MUST be implemented. - -**Exclude** -If the `TagPropagationFilterAction` is Exclude then any `Tag` whose `TagKey` evaluates to true -with the condition (`TagPropagationFitlerMatchOperator` and `TagPropagationFilterMatchString`) -MUST be excluded. - -**Include** -If the `TagPropagationFilterAction` is Include then any `Tag` whose `TagKey` evaluates to true -with the condition (`TagPropagationFitlerMatchOperator ` and `TagPropagationFilterMatchString`) -MUST be included. - -#### TagPropagationFilterMatchOperator - -| Operator | Description | -|----------|-------------| -| EQUAL | The condition is evaluated to true if `TagKey` is exactly same as `TagPropagationFilterMatchString` | -| NOTEQUAL | The condition is evaluated to true if `TagKey` is NOT exactly same as `TagPropagationFilterMatchString` | -| HAS_PREFIX | The condition is evaluated to true if `TagKey` begins with `TagPropagationFilterMatchString` | - -#### TagPropagationFilterMatchString -It is a string to compare against TagKey using `TagPropagationFilterMatchOperator` in order to -include or exclude a `Tag`. - -## Encoding - -### Wire Format -TBD: - -#### Over gRPC -TagMap should be encoded using [BinaryEncoding](https://github.com/census-instrumentation/opencensus-specs/tree/master/encodings) -and propagated using gRPC metadata `grpc-tags-bin`. The propagation MUST inject a TagMap and MUST extract a TagMap from the gRPC metadata. - -#### Over HTTP - -TBD: W3C [correlation context](https://github.com/w3c/correlation-context/blob/master/correlation_context/HTTP_HEADER_FORMAT.md) -may be an appropriate choice. - - -### Error handling -- Call should continue irrespective of any error related to encoding/decoding. -- There are no partial failures for encoding or decoding. The result of encoding or decoding - should always be a complete `TagMap` or an error. The type of error - reporting depends on the language. -- Serialization should result in an error if the `TagMap` does not meet the - size restriction above. -- Deserialization should result in an error if the serialized `TagMap` - - cannot be parsed. - - contains a `TagKey` or `TagValue` that does not meet the restrictions above. - - does not meet the size restriction above.