From a4b1b695905437fd29d5dcfd9f4c8ee34bc8f46b Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 25 Feb 2022 13:48:36 -0800 Subject: [PATCH 1/5] Add documentation requirement for adding attributes at span creation --- specification/trace/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 9e97004454e..bad8cfcec4d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -367,8 +367,9 @@ The API MUST accept the following parameters: description](sdk.md#sampling). An empty collection will be assumed if not specified. - Whenever possible, users SHOULD set any already known attributes at span creation - instead of calling `SetAttribute` later. + Documentation MUST state that adding attributes at span creation is preferred + to calling `SetAttribute` later, as samplers can only consider information + already present during span creation. - `Link`s - an ordered sequence of Links, see API definition [here](#specifying-links). - `Start timestamp`, default to current time. This argument SHOULD only be set From ebbcdb518e4f62b5fccf0ba56abaab6389462675 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 25 Feb 2022 14:04:22 -0800 Subject: [PATCH 2/5] Adding changelog entry --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 631a3ad3250..1dfdef9453d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ release. - Introduce the concept of Instrumentation Scope to replace/extend Instrumentation Library. The Tracer is now associated with Instrumentation Scope ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)). +- Add documentation REQUIREMENT for adding attributes at span creation. + ([#2383](https://github.com/open-telemetry/opentelemetry-specification/pull/2383)). ### Metrics From 258f447a2b29f640ac2ee797365e51b50f1ef04c Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 1 Mar 2022 14:30:25 -0800 Subject: [PATCH 3/5] Update specification/trace/api.md Co-authored-by: Armin Ruech --- 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 bad8cfcec4d..7a1b9a7aeed 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -367,7 +367,7 @@ The API MUST accept the following parameters: description](sdk.md#sampling). An empty collection will be assumed if not specified. - Documentation MUST state that adding attributes at span creation is preferred + The API documentation MUST state that adding attributes at span creation is preferred to calling `SetAttribute` later, as samplers can only consider information already present during span creation. From 986f7a82341488ff93feba549ff535370c432241 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 1 Mar 2022 14:38:11 -0800 Subject: [PATCH 4/5] Add documentation requirement to spec compliance matrix --- spec-compliance-matrix.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2539686b937..7dccbf40d15 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -29,6 +29,7 @@ formats is required. Implementing more than one format is optional. | Set active Span | | N/A | + | + | + | + | + | + | + | + | + | + | | [Tracer](specification/trace/api.md#tracer-operations) | | | | | | | | | | | | | | Create a new Span | | + | + | + | + | + | + | + | + | + | + | + | +| Documentation for adding attributes at span creation | | | | | | | | | | | | | | Get active Span | | N/A | + | + | + | + | + | + | + | + | + | + | | Mark Span active | | N/A | + | + | + | + | + | + | + | + | + | + | | Safe for concurrent calls | | + | + | + | + | + | + | + | + | + | + | + | From 6c2be032a64db70cbf99a903800717754c914080 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 2 Mar 2022 06:56:04 -0800 Subject: [PATCH 5/5] Update spec-compliance-matrix.md Co-authored-by: Armin Ruech --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 7dccbf40d15..6f0ae8c43dc 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -29,7 +29,7 @@ formats is required. Implementing more than one format is optional. | Set active Span | | N/A | + | + | + | + | + | + | + | + | + | + | | [Tracer](specification/trace/api.md#tracer-operations) | | | | | | | | | | | | | | Create a new Span | | + | + | + | + | + | + | + | + | + | + | + | -| Documentation for adding attributes at span creation | | | | | | | | | | | | | +| Documentation defines adding attributes at span creation as preferred | | | | | | | | | | | | | | Get active Span | | N/A | + | + | + | + | + | + | + | + | + | + | | Mark Span active | | N/A | + | + | + | + | + | + | + | + | + | + | | Safe for concurrent calls | | + | + | + | + | + | + | + | + | + | + | + |