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

Update Tracing API: IsRecording wording #3020

Merged
merged 10 commits into from
Dec 16, 2022
Merged

Update Tracing API: IsRecording wording #3020

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bcfc27e
Update Tracing API: IsRecording wording
utezduyar Dec 7, 2022
0ed0585
Correct the formulation
utezduyar Dec 13, 2022
d403e18
Update specification/trace/api.md
utezduyar Dec 14, 2022
145745c
Update specification/trace/api.md
utezduyar Dec 14, 2022
4a05ff2
Update api.md
utezduyar Dec 14, 2022
4af1fa8
Update api.md
utezduyar Dec 15, 2022
aecc821
Update api.md
utezduyar Dec 15, 2022
e1984d7
Update specification/trace/api.md
utezduyar Dec 15, 2022
a7b92d3
Update specification/trace/api.md
utezduyar Dec 15, 2022
e818b28
Update specification/trace/api.md
utezduyar Dec 15, 2022
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
30 changes: 16 additions & 14 deletions specification/trace/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -454,14 +454,23 @@ The Span interface MUST provide:

#### IsRecording

Returns true if this `Span` is recording information like events with the
`AddEvent` operation, attributes using `SetAttributes`, status with `SetStatus`,
etc.
A `Span` is recording (`IsRecording` returns `true`) when the data provided to
it via functions like `SetAttributes`, `AddEvent`, `SetStatus` is captured in
some form (e.g. in memory). When a `Span` is not recording (`IsRecording` returns
`false`), all this data is discarded right away. Further attempts to set or add
data will not record, making the span effectively a no-op.

This flag may be `true` despite the entire trace not being sampled. This
allows information about the individual Span to be recorded and processed without
sending it to the backend. An example of this scenario may be recording and
processing of all incoming requests for the processing and building of
SLA/SLO latency charts while sending only a subset - sampled spans - to the
backend. See also the [sampling section of SDK design](sdk.md#sampling).
utezduyar marked this conversation as resolved.
Show resolved Hide resolved

After a `Span` is ended, it usually becomes non-recording and thus
`IsRecording` SHOULD consequently return false for ended Spans.
Note: Streaming implementations, where it is not known if a span is ended,
are one expected case where `IsRecording` cannot change after ending a Span.
After a `Span` is ended, it SHOULD become non-recording and `IsRecording`
SHOULD always return `false`. The one known exception to this is
streaming implementations of the API that do not keep local state and cannot
change the value of `IsRecording` after ending the span.

`IsRecording` SHOULD NOT take any parameters.

Expand All @@ -471,13 +480,6 @@ span's recording is determined independently from the value of this flag
(typically based on the `sampled` flag of a `TraceFlags` on
[SpanContext](#spancontext)).

This flag may be `true` despite the entire trace being sampled out. This
allows to record and process information about the individual Span without
sending it to the backend. An example of this scenario may be recording and
processing of all incoming requests for the processing and building of
SLA/SLO latency charts while sending only a subset - sampled spans - to the
backend. See also the [sampling section of SDK design](sdk.md#sampling).

Users of the API should only access the `IsRecording` property when
instrumenting code and never access `SampledFlag` unless used in context
propagators.
Expand Down