diff --git a/specification/trace/api.md b/specification/trace/api.md index 9b85fa44254..d27cbacc9f7 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -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). -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. @@ -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.