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

Add description of TraceState operations #905

Merged
merged 7 commits into from
Sep 3, 2020
Merged

Add description of TraceState operations #905

Show file tree
Hide file tree
Changes from 5 commits
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
7 changes: 3 additions & 4 deletions specification/trace/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,11 +175,10 @@ byte.
TraceFlags are present in all traces. The current version of the specification
only supports a single flag called [sampled](https://www.w3.org/TR/trace-context/#sampled-flag).

`TraceState` carries system-specific configuration data, represented as a list
`TraceState` carries vendor-specific trace identification data, represented as a list
of key-value pairs. TraceState allows multiple tracing
systems to participate in the same trace. Please review the [W3C
specification](https://www.w3.org/TR/trace-context/#tracestate-header) for
details on this field.
systems to participate in the same trace. It is fully described in the [W3C Trace Context
specification](https://www.w3.org/TR/trace-context/#tracestate-header).

### Retrieving the TraceId and SpanId

Expand Down
24 changes: 24 additions & 0 deletions specification/trace/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,30 @@ 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

`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`:

* 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 MUST follow the [general error handling guidelines](../error-handling.md) (e.g. it usually must not return null or throw an exception).

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
[`SpanContext` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md)
or [telemetry data exporting](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter).
In both cases, `Propagators` and `SpanExporters` may create a modified `TraceState` copy before serializing it to the wire.

## Span processor

Span processor is an interface which allows hooks for span start and end method
Expand Down