From 45628437a2ea6112a050765ed4b626908e947baa Mon Sep 17 00:00:00 2001 From: Mike Goldsmth Date: Mon, 27 Jan 2020 10:36:26 -0800 Subject: [PATCH 1/2] remove binary format --- specification/api-propagators.md | 36 +------------------------------- specification/api-tracing.md | 8 +++---- specification/overview.md | 3 +-- 3 files changed, 5 insertions(+), 42 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 5dd6433eda6..0d5aab06239 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -5,9 +5,6 @@ Table of Contents -- [Binary Format](#binary-format) - - [ToBytes](#tobytes) - - [FromBytes](#frombytes) - [HTTP Text Format](#http-text-format) - [Fields](#fields) - [Inject](#inject) @@ -19,44 +16,13 @@ Table of Contents -Propagators API consists of two main formats: +Propagators API consists of one main format: -- `BinaryFormat` is used to serialize and deserialize a value into a binary representation. - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel in-band across process boundaries. Deserializing must set `IsRemote` to true on the returned `SpanContext`. -## Binary Format - -`BinaryFormat` is a formatter to serialize and deserialize a value into a binary format. - -`BinaryFormat` MUST expose the APIs that serializes values into bytes, -and deserializes values from bytes. - -### ToBytes - -Serializes the given value into the on-the-wire representation. - -Required arguments: - -- the value to serialize, can be `SpanContext` or `DistributedContext`. - -Returns the on-the-wire byte representation of the value. - -### FromBytes - -Creates a value from the given on-the-wire encoded representation. - -If the value could not be parsed, the underlying implementation SHOULD decide to return ether -an empty value, an invalid value, or a valid value. - -Required arguments: - -- on-the-wire byte representation of the value. - -Returns a value deserialized from bytes. - ## HTTP Text Format `HTTPTextFormat` is a formatter that injects and extracts a value as text into carriers that diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6702d1ef596..b1dad43d954 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -15,7 +15,6 @@ Table of Contents * [GetCurrentSpan](#getcurrentspan) * [WithSpan](#withspan) * [SpanBuilder](#spanbuilder) - * [GetBinaryFormat](#getbinaryformat) * [GetHttpTextFormat](#gethttptextformat) * [SpanContext](#spancontext) * [Span](#span) @@ -131,9 +130,8 @@ The `Tracer` MUST provide methods to: - Make a given `Span` as active The `Tracer` SHOULD allow end users to configure other tracing components that -control how `Span`s are passed across process boundaries, including the binary -and text format `Propagator`s used to serialize `Span`s created by the -`Tracer`. +control how `Span`s are passed across process boundaries, including the text +format `Propagator` used to serialize `Span`s created by the `Tracer`. When getting the current span, the `Tracer` MUST return a placeholder `Span` with an invalid `SpanContext` if there is no currently active `Span`. @@ -151,7 +149,7 @@ convenience methods to manage a `Span`'s lifetime and the scope in which a time) but stil active. A `Span` may be active on one thread after it has been made inactive on another. -The implementation MUST provide no-op binary and text `Propagator`s, which the +The implementation MUST provide a text `Propagator`, which the `Tracer` SHOULD use by default if other propagators are not configured. SDKs SHOULD use the W3C HTTP Trace Context as the default text format. For more details, see [trace-context](https://github.com/w3c/trace-context). diff --git a/specification/overview.md b/specification/overview.md index e80e9e5ecd2..a027ee1c40b 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -238,9 +238,8 @@ for an example. ## Propagators OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext` -into a binary or text format. Currently there are two types of propagators: +into text format. Currently there is one type of propagator: -- `BinaryFormat` which is used to serialize and deserialize a value into a binary representation. - `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel in-band across process boundaries. From c8dab1a1e67307689cf22718fc937c675585f276 Mon Sep 17 00:00:00 2001 From: Mike Goldsmth Date: Thu, 6 Feb 2020 11:45:34 +0000 Subject: [PATCH 2/2] add note about re-adding binary format in future --- specification/api-propagators.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 0d5aab06239..484b6bdf77d 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -16,13 +16,15 @@ Table of Contents -Propagators API consists of one main format: +Propagators API currently consists of one format: - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel in-band across process boundaries. Deserializing must set `IsRemote` to true on the returned `SpanContext`. +A binary format will be added in the future. + ## HTTP Text Format `HTTPTextFormat` is a formatter that injects and extracts a value as text into carriers that