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.
This commit is contained in:
Yang Song
Sergey Kanzhelev
parent
c707a8bac3
commit
db519d6220
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue