open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2019-06-10 15:37:30 -07:00 committed by Sergey Kanzhelev
parent c707a8bac3
commit db519d6220
3 changed files with 16 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
terminology.md
View File

@ -106,9 +106,23 @@ Trace instead of trusting incoming Trace context.
TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemetry-specification/issues/45 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 ## Resources

6
work_in_progress/specification/tags/README.md
View File

@ -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)

189
work_in_progress/specification/tags/TagMap.md
View File

@ -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.