From bcfc27e891dc5dc32c319a39220047b11dd710c9 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Wed, 7 Dec 2022 08:16:03 +0100 Subject: [PATCH 01/10] Update Tracing API: IsRecording wording https://github.com/open-telemetry/opentelemetry-specification/issues/3006 --- specification/trace/api.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 9b85fa44254..22eed6d7b9e 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -454,15 +454,16 @@ 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. - +Returns `true` if this `Span` has been started but not ended. After a `Span` is ended, it usually becomes non-recording and thus -`IsRecording` SHOULD consequently return false for ended Spans. +`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. +Recording information like events with the `AddEvent` operation, attributes +using `SetAttributes`, status with `SetStatus`, etc will not perform if +`IsRecording` returns `false`. + `IsRecording` SHOULD NOT take any parameters. This flag SHOULD be used to avoid expensive computations of a Span attributes or From 0ed058515aa009b476232ecd9bc156dc191df389 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Tue, 13 Dec 2022 14:02:47 +0100 Subject: [PATCH 02/10] Correct the formulation Take in to consideration of non recording spans. --- specification/trace/api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 22eed6d7b9e..b45d7e32ff8 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -454,7 +454,9 @@ The Span interface MUST provide: #### IsRecording -Returns `true` if this `Span` has been started but not ended. +Always returns `false` If this is a non-recording `Span` (Sampling +`Decision` was `DROP` at the time of `Span` creation). Otherwise returns +`true` if this `Span` has been started but not ended. 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, From d403e18529861b57b25b009e228276bd79e0c47d Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Wed, 14 Dec 2022 08:11:29 +0100 Subject: [PATCH 03/10] Update specification/trace/api.md Co-authored-by: Joshua MacDonald --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index b45d7e32ff8..d4c8cb14e5f 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -463,7 +463,7 @@ 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. Recording information like events with the `AddEvent` operation, attributes -using `SetAttributes`, status with `SetStatus`, etc will not perform if +using `SetAttributes`, status with `SetStatus`, etc will not perform when `IsRecording` returns `false`. `IsRecording` SHOULD NOT take any parameters. From 145745c58b58302219c0e50f71b5bb78228171fb Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Wed, 14 Dec 2022 08:32:25 +0100 Subject: [PATCH 04/10] Update specification/trace/api.md Co-authored-by: Yuri Shkuro --- specification/trace/api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index d4c8cb14e5f..8b4e2ad7cd5 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -454,8 +454,7 @@ The Span interface MUST provide: #### IsRecording -Always returns `false` If this is a non-recording `Span` (Sampling -`Decision` was `DROP` at the time of `Span` creation). Otherwise returns +Always returns `false` If this is a non-recording `Span`. Otherwise returns `true` if this `Span` has been started but not ended. After a `Span` is ended, it usually becomes non-recording and thus `IsRecording` SHOULD consequently return `false` for ended Spans. From 4a05ff2bc160c2d2f187e13d68446e4223f5eb31 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Wed, 14 Dec 2022 08:48:44 +0100 Subject: [PATCH 05/10] Update api.md --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 8b4e2ad7cd5..6ddb3f38ff5 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -462,7 +462,7 @@ 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. Recording information like events with the `AddEvent` operation, attributes -using `SetAttributes`, status with `SetStatus`, etc will not perform when +using `SetAttributes`, status with `SetStatus`, etc will be discarded when `IsRecording` returns `false`. `IsRecording` SHOULD NOT take any parameters. From 4af1fa837daadbc580fd0bf0f927dbff73449b59 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Thu, 15 Dec 2022 08:36:41 +0100 Subject: [PATCH 06/10] Update api.md --- specification/trace/api.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 6ddb3f38ff5..8076270449c 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -454,16 +454,23 @@ The Span interface MUST provide: #### IsRecording -Always returns `false` If this is a non-recording `Span`. Otherwise returns -`true` if this `Span` has been started but not ended. -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. - -Recording information like events with the `AddEvent` operation, attributes -using `SetAttributes`, status with `SetStatus`, etc will be discarded when -`IsRecording` returns `false`. +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 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). + +After a `Span` is ended, it SHOULD become non-recording and its `IsRecording` +SHOULD start consequently 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. From aecc8216a95904963ed25e1906fc6f9fda959638 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Thu, 15 Dec 2022 20:52:30 +0100 Subject: [PATCH 07/10] Update api.md --- specification/trace/api.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 8076270449c..6de1a53ac54 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -480,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. From e1984d780fd685c484bcea7b8efa9d523d3945fe Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Thu, 15 Dec 2022 21:18:41 +0100 Subject: [PATCH 08/10] Update specification/trace/api.md Co-authored-by: Yuri Shkuro --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 6de1a53ac54..6bbeeaa8780 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -460,7 +460,7 @@ some form (e.g. in memory). When a `Span` is not recording (`IsRecording` return `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 being sampled out. This +This flag may be `true` despite the entire trace not being sampled. 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 From a7b92d3e0a821aeb9e3eededd82696992197e442 Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Thu, 15 Dec 2022 21:52:51 +0100 Subject: [PATCH 09/10] Update specification/trace/api.md Co-authored-by: Tyler Yahn --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 6bbeeaa8780..66be8bc8d54 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -461,7 +461,7 @@ some form (e.g. in memory). When a `Span` is not recording (`IsRecording` return 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 to record and process information about the individual Span without +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 From e818b288ac3b0f81902481fbf4d7865985412f0e Mon Sep 17 00:00:00 2001 From: Umut Tezduyar Lindskog Date: Thu, 15 Dec 2022 21:53:18 +0100 Subject: [PATCH 10/10] Update specification/trace/api.md Co-authored-by: Tyler Yahn --- specification/trace/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 66be8bc8d54..d27cbacc9f7 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -467,8 +467,8 @@ 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 SHOULD become non-recording and its `IsRecording` -SHOULD start consequently return `false`. The one known exception to this is +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.