Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add description of TraceState operations #905

Merged
merged 7 commits into from
Sep 3, 2020
Merged

Add description of TraceState operations #905

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f52e1ab
Add description of TraceState operations
iNikem Sep 1, 2020
88b8432
Apply suggestions from code review
iNikem Sep 1, 2020
f762be8
Apply suggestions from code review
iNikem Sep 1, 2020
2b6c28c
Add validation requirement
iNikem Sep 2, 2020
d189728
Fix error handling
iNikem Sep 2, 2020
f1b18f6
Merge branch 'master' into tracecontext
SergeyKanzhelev Sep 2, 2020
ffbcd41
Merge branch 'master' into tracecontext
SergeyKanzhelev Sep 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions specification/trace/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,17 +229,23 @@ Thus, the SDK specification defines sets of possible requirements for
(for example, the `Span` could be one of the parameters passed to such a function,
or a getter could be provided).

## TraceState manipulation
## TraceState

`TraceState` is a part of [`SpanContext`](./api.md#spancontext), represented by a list of string key-value pairs and
`TraceState` is a part of [`SpanContext`](./api.md#spancontext), represented by an immutable list of string key/value pairs and
formally defined by the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header).
Tracing SDK MUST provide at least the following operations on `TraceState` which return a new `TraceState` with the modifications applied:
Tracing SDK MUST provide at least the following operations on `TraceState`:

* Update key value
* Get value for a given key
* Add a new key/value pair
* Update an existing value for a given key
* Delete a key/value pair

These operations MUST follow the rules described in the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#mutating-the-tracestate-field).
iNikem marked this conversation as resolved.
Show resolved Hide resolved
All mutating operations MUST return a new `TraceState` with the modifications applied.
`TraceState` MUST at all times be valid according to rules specified in [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header-field-values).
Every mutating operations MUST validate input parameters.
If invalid value is passed the operation MUST NOT return `TraceState` containing invalid data
and SHOULD signal an error situation in a language specific way (e.g. throw an exception in java, return error value in Go, etc).
iNikem marked this conversation as resolved.
Show resolved Hide resolved

Please note, since `SpanContext` is immutable, it is not possible to update `SpanContext` with a new `TraceState`.
Such changes then make sense only right before
Expand Down