From fd20911e14998c8d4ed215db9d6ac3bc5448e040 Mon Sep 17 00:00:00 2001 From: songy23 Date: Fri, 14 Jun 2019 14:50:26 -0700 Subject: [PATCH 1/6] Add specs on Span creation. Fixes #37. --- specification/tracing-api.md | 47 +++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 11 deletions(-) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index 85d60a75a13..b42fab8e2a1 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -14,13 +14,13 @@ Table of Content * [Tracer operations](#tracer-operations) * [GetCurrentSpan](#getcurrentspan) * [WithSpan](#withspan) - * [SpanBuilder](#spanbuilder) * [RecordSpanData](#recordspandata) * [GetBinaryFormat](#getbinaryformat) * [GetHttpTextFormat](#gethttptextformat) * [SpanContext](#spancontext) * [Span](#span) * [Span creation](#span-creation) + * [StartSpan](#startspan) * [Span operations](#span-operations) * [GetContext](#getcontext) * [IsRecordingEvents](#isrecordingevents) @@ -106,15 +106,6 @@ Returns an object that defines a scope where the given `Span` will be set to the The scope is exited and previous state should be restored when the returned object is closed. -#### SpanBuilder -Returns a `SpanBuilder` to create and start a new `Span`. - -Required parameters: - -- Name of the span. - -Returns a `SpanBuilder` to create and start a new `Span`. - #### RecordSpanData Records a `SpanData`. @@ -191,7 +182,41 @@ creation](#span-creation). ### Span creation -TODO: SpanBuilder API https://github.com/open-telemetry/opentelemetry-specification/issues/37 +API MUST provide a way to create a new `Span`. Each language implementation should +follow its own convention on `Span` creation, for example `Builder` in Java, +`Options` in Go, etc. + +Required parameters: + +- Name of the span. + +Optional parameters (or corresponding setters on `Builder` if using a `Builder` pattern): + +- Parent `Span`. If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) +at `StartSpan` time will be used as parent. MUST be used to create a `Span` +when manual Context propagation is used OR when creating a root `Span` with +a parent with an invalid `SpanContext`. +- Parent `SpanContext`. If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) +at `StartSpan` time will be used as parent. MUST be used to create a `Span` +when the parent is in a different process. +- The option to become a root `Span` for a new trace. +If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) at `StartSpan` +time will be used as parent. +- `Sampler` to the newly created `Span`. If not set, the implementation should provide a default. +- `Link` to the newly created `Span`. +- The option to record events even if not sampled for the newly created `Span`. If +not called, the implementation will provide a default. +- `SpanKind` for the newly created `Span`. If not called, the implementation will +provide a default value `INTERNAL`. + +#### StartSpan + +Starts a new `Span`. + +There should be no parameter if using a `Builder` pattern. Otherwise, `StartSpan` +should accept all the optional parameters described in [Span creation](#span-creation). + +Returns the newly created `Span`. ### Span operations From 37479632870bba23e12f907d271a1fa0f1ffa4aa Mon Sep 17 00:00:00 2001 From: songy23 Date: Fri, 14 Jun 2019 15:23:38 -0700 Subject: [PATCH 2/6] Put back Tracer.SpanBuilder --- specification/tracing-api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index b42fab8e2a1..2079c79e006 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -14,6 +14,7 @@ Table of Content * [Tracer operations](#tracer-operations) * [GetCurrentSpan](#getcurrentspan) * [WithSpan](#withspan) + * [SpanBuilder](#spanbuilder) * [RecordSpanData](#recordspandata) * [GetBinaryFormat](#getbinaryformat) * [GetHttpTextFormat](#gethttptextformat) @@ -106,6 +107,16 @@ Returns an object that defines a scope where the given `Span` will be set to the The scope is exited and previous state should be restored when the returned object is closed. +#### SpanBuilder +Returns a `SpanBuilder` to create and start a new `Span` +if a `Builder` pattern for [Span creation](#span-creation) is used. + +Required parameters: + +- Name of the span. + +Returns a `SpanBuilder` to create and start a new `Span`. + #### RecordSpanData Records a `SpanData`. From a7e7ec046909268dd80ea41758daa131ffe5d16a Mon Sep 17 00:00:00 2001 From: Yang Song Date: Fri, 14 Jun 2019 15:26:42 -0700 Subject: [PATCH 3/6] s/called/set Co-Authored-By: Sergey Kanzhelev --- specification/tracing-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index 2079c79e006..bb8de252caa 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -217,7 +217,7 @@ time will be used as parent. - `Link` to the newly created `Span`. - The option to record events even if not sampled for the newly created `Span`. If not called, the implementation will provide a default. -- `SpanKind` for the newly created `Span`. If not called, the implementation will +- `SpanKind` for the newly created `Span`. If not set, the implementation will provide a default value `INTERNAL`. #### StartSpan From 6e03ea0bfa899ae488a27615ba32d6e9665c1209 Mon Sep 17 00:00:00 2001 From: songy23 Date: Fri, 14 Jun 2019 15:30:33 -0700 Subject: [PATCH 4/6] Fix spaces. Add a note about span creation from Tracer. --- specification/tracing-api.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index bb8de252caa..f74d5cd1fbc 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -195,7 +195,7 @@ creation](#span-creation). API MUST provide a way to create a new `Span`. Each language implementation should follow its own convention on `Span` creation, for example `Builder` in Java, -`Options` in Go, etc. +`Options` in Go, etc. `Span` creation method MUST be defined on `Tracer`. Required parameters: @@ -204,21 +204,21 @@ Required parameters: Optional parameters (or corresponding setters on `Builder` if using a `Builder` pattern): - Parent `Span`. If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) -at `StartSpan` time will be used as parent. MUST be used to create a `Span` -when manual Context propagation is used OR when creating a root `Span` with -a parent with an invalid `SpanContext`. + at `StartSpan` time will be used as parent. MUST be used to create a `Span` + when manual Context propagation is used OR when creating a root `Span` with + a parent with an invalid `SpanContext`. - Parent `SpanContext`. If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) -at `StartSpan` time will be used as parent. MUST be used to create a `Span` -when the parent is in a different process. + at `StartSpan` time will be used as parent. MUST be used to create a `Span` + when the parent is in a different process. - The option to become a root `Span` for a new trace. -If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) at `StartSpan` -time will be used as parent. + If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) at `StartSpan` + time will be used as parent. - `Sampler` to the newly created `Span`. If not set, the implementation should provide a default. - `Link` to the newly created `Span`. - The option to record events even if not sampled for the newly created `Span`. If -not called, the implementation will provide a default. + not set, the implementation will provide a default. - `SpanKind` for the newly created `Span`. If not set, the implementation will -provide a default value `INTERNAL`. + provide a default value `INTERNAL`. #### StartSpan From 8dbbd9111d3e88cd8b6dcc9d4e70252758cf6f7f Mon Sep 17 00:00:00 2001 From: songy23 Date: Fri, 14 Jun 2019 15:41:01 -0700 Subject: [PATCH 5/6] Update recordEvents and StartSpan. --- specification/tracing-api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index f74d5cd1fbc..35930c43141 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -215,8 +215,8 @@ Optional parameters (or corresponding setters on `Builder` if using a `Builder` time will be used as parent. - `Sampler` to the newly created `Span`. If not set, the implementation should provide a default. - `Link` to the newly created `Span`. -- The option to record events even if not sampled for the newly created `Span`. If - not set, the implementation will provide a default. +- The override value for [a flag indicating whether events should be recorded](#isrecordingevents) + for the newly created `Span`. If not set, the implementation will provide a default. - `SpanKind` for the newly created `Span`. If not set, the implementation will provide a default value `INTERNAL`. @@ -224,6 +224,8 @@ Optional parameters (or corresponding setters on `Builder` if using a `Builder` Starts a new `Span`. +This MUST not be called multiple times with `Builder` pattern. + There should be no parameter if using a `Builder` pattern. Otherwise, `StartSpan` should accept all the optional parameters described in [Span creation](#span-creation). From cd1e5f7738b8cf8aa13d10c1890ef0305e4a195f Mon Sep 17 00:00:00 2001 From: songy23 Date: Fri, 14 Jun 2019 16:00:23 -0700 Subject: [PATCH 6/6] Update default samplers, links and StartSpan. --- specification/tracing-api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/tracing-api.md b/specification/tracing-api.md index 35930c43141..aafd796f3e7 100644 --- a/specification/tracing-api.md +++ b/specification/tracing-api.md @@ -213,8 +213,9 @@ Optional parameters (or corresponding setters on `Builder` if using a `Builder` - The option to become a root `Span` for a new trace. If not set, the value of [Tracer.getCurrentSpan](#getcurrentspan) at `StartSpan` time will be used as parent. -- `Sampler` to the newly created `Span`. If not set, the implementation should provide a default. -- `Link` to the newly created `Span`. +- `Sampler` to the newly created `Span`. If not set, the implementation should provide a + default sampler used by Tracer. +- Collection of `Link`s that will be associated with the newly created Span - The override value for [a flag indicating whether events should be recorded](#isrecordingevents) for the newly created `Span`. If not set, the implementation will provide a default. - `SpanKind` for the newly created `Span`. If not set, the implementation will @@ -224,7 +225,7 @@ Optional parameters (or corresponding setters on `Builder` if using a `Builder` Starts a new `Span`. -This MUST not be called multiple times with `Builder` pattern. +If called multiple times with `Builder` pattern, the same `Span` will be returned. There should be no parameter if using a `Builder` pattern. Otherwise, `StartSpan` should accept all the optional parameters described in [Span creation](#span-creation).