From 19ba6d2c9e706bdafcc0419ca606e7226ff4ea20 Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Mon, 29 Mar 2021 17:36:15 -0700 Subject: [PATCH 1/5] refactor!: do not export B3SinglePropagator and B3MultiPropagator --- .../test/context/composite.test.ts | 13 +++++++--- .../src/B3MultiPropagator.ts | 14 +++++------ .../src/B3Propagator.ts | 3 ++- .../src/B3SinglePropagator.ts | 4 +-- .../src/constants.ts | 25 +++++++++++++++++++ .../opentelemetry-propagator-b3/src/index.ts | 3 +-- .../test/B3MultiPropagator.test.ts | 4 +-- .../test/B3Propagator.test.ts | 4 +-- .../test/B3SinglePropagator.test.ts | 6 ++--- 9 files changed, 52 insertions(+), 24 deletions(-) create mode 100644 packages/opentelemetry-propagator-b3/src/constants.ts diff --git a/packages/opentelemetry-core/test/context/composite.test.ts b/packages/opentelemetry-core/test/context/composite.test.ts index 52114aeeb9..6addee1ff2 100644 --- a/packages/opentelemetry-core/test/context/composite.test.ts +++ b/packages/opentelemetry-core/test/context/composite.test.ts @@ -30,7 +30,8 @@ import { RandomIdGenerator, } from '../../src'; import { - B3MultiPropagator, + B3Propagator, + B3InjectEncoding, X_B3_SAMPLED, X_B3_SPAN_ID, X_B3_TRACE_ID, @@ -69,7 +70,10 @@ describe('Composite Propagator', () => { it('should inject context using all configured propagators', () => { const composite = new CompositePropagator({ - propagators: [new B3MultiPropagator(), new HttpTraceContext()], + propagators: [ + new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }), + new HttpTraceContext(), + ], }); composite.inject(ctxWithSpanContext, carrier, defaultTextMapSetter); @@ -111,7 +115,10 @@ describe('Composite Propagator', () => { it('should extract context using all configured propagators', () => { const composite = new CompositePropagator({ - propagators: [new B3MultiPropagator(), new HttpTraceContext()], + propagators: [ + new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }), + new HttpTraceContext(), + ], }); const spanContext = getSpanContext( composite.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter) diff --git a/packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts b/packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts index 7f0e414c05..cea1f4a445 100644 --- a/packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts +++ b/packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts @@ -26,15 +26,15 @@ import { TextMapSetter, TraceFlags, } from '@opentelemetry/api'; +import { + X_B3_TRACE_ID, + X_B3_SPAN_ID, + X_B3_SAMPLED, + X_B3_PARENT_SPAN_ID, + X_B3_FLAGS, +} from './constants'; import { B3_DEBUG_FLAG_KEY } from './common'; -/* b3 multi-header keys */ -export const X_B3_TRACE_ID = 'x-b3-traceid'; -export const X_B3_SPAN_ID = 'x-b3-spanid'; -export const X_B3_SAMPLED = 'x-b3-sampled'; -export const X_B3_PARENT_SPAN_ID = 'x-b3-parentspanid'; -export const X_B3_FLAGS = 'x-b3-flags'; - const VALID_SAMPLED_VALUES = new Set([true, 'true', 'True', '1', 1]); const VALID_UNSAMPLED_VALUES = new Set([false, 'false', 'False', '0', 0]); diff --git a/packages/opentelemetry-propagator-b3/src/B3Propagator.ts b/packages/opentelemetry-propagator-b3/src/B3Propagator.ts index a1b09635f8..d0f1c96540 100644 --- a/packages/opentelemetry-propagator-b3/src/B3Propagator.ts +++ b/packages/opentelemetry-propagator-b3/src/B3Propagator.ts @@ -21,7 +21,8 @@ import { TextMapSetter, } from '@opentelemetry/api'; import { B3MultiPropagator } from './B3MultiPropagator'; -import { B3SinglePropagator, B3_CONTEXT_HEADER } from './B3SinglePropagator'; +import { B3SinglePropagator } from './B3SinglePropagator'; +import { B3_CONTEXT_HEADER } from './constants'; import { B3InjectEncoding, B3PropagatorConfig } from './types'; /** diff --git a/packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts b/packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts index 8e751cfb79..b75f4cd302 100644 --- a/packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts +++ b/packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts @@ -26,11 +26,9 @@ import { TextMapSetter, TraceFlags, } from '@opentelemetry/api'; +import { B3_CONTEXT_HEADER } from './constants'; import { B3_DEBUG_FLAG_KEY } from './common'; -/** B3 single-header name */ -export const B3_CONTEXT_HEADER = 'b3'; - const B3_CONTEXT_REGEX = /((?:[0-9a-f]{16}){1,2})-([0-9a-f]{16})(?:-([01d](?![0-9a-f])))?(?:-([0-9a-f]{16}))?/; const PADDING = '0'.repeat(16); const SAMPLED_VALUES = new Set(['d', '1']); diff --git a/packages/opentelemetry-propagator-b3/src/constants.ts b/packages/opentelemetry-propagator-b3/src/constants.ts new file mode 100644 index 0000000000..cd60c865cf --- /dev/null +++ b/packages/opentelemetry-propagator-b3/src/constants.ts @@ -0,0 +1,25 @@ +/* + * Copyright The OpenTelemetry Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** B3 single-header key */ +export const B3_CONTEXT_HEADER = 'b3'; + +/* b3 multi-header keys */ +export const X_B3_TRACE_ID = 'x-b3-traceid'; +export const X_B3_SPAN_ID = 'x-b3-spanid'; +export const X_B3_SAMPLED = 'x-b3-sampled'; +export const X_B3_PARENT_SPAN_ID = 'x-b3-parentspanid'; +export const X_B3_FLAGS = 'x-b3-flags'; diff --git a/packages/opentelemetry-propagator-b3/src/index.ts b/packages/opentelemetry-propagator-b3/src/index.ts index 3fb23f4fda..5bc5069e1f 100644 --- a/packages/opentelemetry-propagator-b3/src/index.ts +++ b/packages/opentelemetry-propagator-b3/src/index.ts @@ -15,6 +15,5 @@ */ export * from './B3Propagator'; -export * from './B3SinglePropagator'; -export * from './B3MultiPropagator'; +export * from './constants'; export * from './types'; diff --git a/packages/opentelemetry-propagator-b3/test/B3MultiPropagator.test.ts b/packages/opentelemetry-propagator-b3/test/B3MultiPropagator.test.ts index 211fd48c3e..759651b59d 100644 --- a/packages/opentelemetry-propagator-b3/test/B3MultiPropagator.test.ts +++ b/packages/opentelemetry-propagator-b3/test/B3MultiPropagator.test.ts @@ -24,14 +24,14 @@ import { } from '@opentelemetry/api'; import { ROOT_CONTEXT } from '@opentelemetry/api'; import * as assert from 'assert'; +import { B3MultiPropagator } from '../src/B3MultiPropagator'; import { - B3MultiPropagator, X_B3_FLAGS, X_B3_PARENT_SPAN_ID, X_B3_SAMPLED, X_B3_SPAN_ID, X_B3_TRACE_ID, -} from '../src/B3MultiPropagator'; +} from '../src/constants'; import { B3_DEBUG_FLAG_KEY } from '../src/common'; describe('B3MultiPropagator', () => { diff --git a/packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts b/packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts index e68216e187..a25bd468d3 100644 --- a/packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts +++ b/packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts @@ -26,14 +26,14 @@ import { } from '@opentelemetry/api'; import { B3Propagator } from '../src/B3Propagator'; import { B3InjectEncoding } from '../src/types'; -import { B3_CONTEXT_HEADER } from '../src/B3SinglePropagator'; import { + B3_CONTEXT_HEADER, X_B3_FLAGS, X_B3_PARENT_SPAN_ID, X_B3_SAMPLED, X_B3_SPAN_ID, X_B3_TRACE_ID, -} from '../src/B3MultiPropagator'; +} from '../src/constants'; describe('B3Propagator', () => { let propagator: B3Propagator; diff --git a/packages/opentelemetry-propagator-b3/test/B3SinglePropagator.test.ts b/packages/opentelemetry-propagator-b3/test/B3SinglePropagator.test.ts index 02009821d6..feb9c2a3e6 100644 --- a/packages/opentelemetry-propagator-b3/test/B3SinglePropagator.test.ts +++ b/packages/opentelemetry-propagator-b3/test/B3SinglePropagator.test.ts @@ -26,10 +26,8 @@ import { } from '@opentelemetry/api'; import { ROOT_CONTEXT } from '@opentelemetry/api'; import * as assert from 'assert'; -import { - B3SinglePropagator, - B3_CONTEXT_HEADER, -} from '../src/B3SinglePropagator'; +import { B3SinglePropagator } from '../src/B3SinglePropagator'; +import { B3_CONTEXT_HEADER } from '../src/constants'; import { B3_DEBUG_FLAG_KEY } from '../src/common'; describe('B3SinglePropagator', () => { From f96861cd164af79381c07f9128c593a35077d060 Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Mon, 29 Mar 2021 17:41:02 -0700 Subject: [PATCH 2/5] docs: update b3 propagator readme --- .../opentelemetry-propagator-b3/README.md | 63 ++----------------- 1 file changed, 5 insertions(+), 58 deletions(-) diff --git a/packages/opentelemetry-propagator-b3/README.md b/packages/opentelemetry-propagator-b3/README.md index 5748ebc74c..cc033bdcd4 100644 --- a/packages/opentelemetry-propagator-b3/README.md +++ b/packages/opentelemetry-propagator-b3/README.md @@ -65,17 +65,15 @@ X-B3-Sampled: {SamplingState} - Optional - Debug is encoded as `X-B3-Flags`: 1. Absent or any other value can be ignored. Debug implies an accept decision, so don't also send the `X-B3-Sampled` header. -## Propagator Implementations - -### B3Propagator +## B3 Propagation The default `B3Propagator` implements b3 propagation according to the [OpenTelemetry specification][otel-b3-requirements]. It extracts b3 context from multi and single header encodings and injects context using the -single-header b3 encoding. The inject encoding can be changed to multi-header -via configuration. +single-header b3 encoding by default. The inject encoding can be changed to +multi-header via configuration. See the examples below. -Example usage (default): +### B3 Single-Header Configuration ```javascript const api = require('@opentelemetry/api'); @@ -84,7 +82,7 @@ const { B3Propagator } = require('@opentelemetry/propagator-b3'); api.propagation.setGlobalPropagator(new B3Propagator()); ``` -Example usage (specify inject encoding): +### B3 Multi-Header Configuration ```javascript const api = require('@opentelemetry/api'); @@ -95,57 +93,6 @@ api.propagation.setGlobalPropagator( ); ``` -### B3SinglePropagator - -If a distributed system only needs support for the b3 single-header -encoding it can use the `B3SinglePropagator` directly. - -Example usage: - -```javascript -const api = require('@opentelemetry/api'); -const { B3SinglePropagator } = require('@opentelemetry/propagator-b3'); - -api.propagation.setGlobalPropagator(new B3SinglePropagator()); -``` - -### B3MultiPropagator - -If a distributed system only needs support for the b3 multi-header -encoding it can use the `B3MultiPropagator` directly. - -Example usage: - -```javascript -const api = require('@opentelemetry/api'); -const { B3MultiPropagator } = require('@opentelemetry/propagator-b3'); - -api.propagation.setGlobalPropagator(new B3MultiPropagator()); -``` - -### CompositePropagator - -If a distributed system needs to support both single and multiple header -encodings for inject and extract the `B3SinglePropagator` and -`B3MultiPropagator` can be used in conjunction with a `CompositePropagator`. - -Example usage: - -```javascript -const api = require('@opentelemetry/api'); -const { CompositePropagator } = require('@opentelemetry/core'); -const { - B3SinglePropagator, - B3MultiPropagator, -} = require('@opentelemetry/propagator-b3'); - -api.propagation.setGlobalPropagator( - new CompositePropagator({ - propagators: [new B3SinglePropagator(), new B3MultiPropagator()], - }) -); -``` - ## Useful links - For more information on OpenTelemetry, visit: From 805478ecaafff5d9dc0def11e4df2c80982044b0 Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 30 Mar 2021 13:48:24 -0700 Subject: [PATCH 3/5] docs: document b3 composite propagator usage --- .../opentelemetry-propagator-b3/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/opentelemetry-propagator-b3/README.md b/packages/opentelemetry-propagator-b3/README.md index cc033bdcd4..5b45b088d5 100644 --- a/packages/opentelemetry-propagator-b3/README.md +++ b/packages/opentelemetry-propagator-b3/README.md @@ -93,6 +93,25 @@ api.propagation.setGlobalPropagator( ); ``` +### B3 Single and Multi-Header Configuration + +The B3Propagator always extracts both the single and multi-header b3 encodings. +If you need to inject both encoding this can accomplished using a composite +propagator. + +```javascript +const api = require('@opentelemetry/api'); +const { B3Propagator } = require('@opentelemetry/propagator-b3'); +api.propagation.setGlobalPropagator( + new CompositePropagator({ + propagators: [ + new B3Propagator(), + new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }), + ], + }) +); +``` + ## Useful links - For more information on OpenTelemetry, visit: From 3ffd8a1c6c0ce47b0347038570fedc78e6e07994 Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 30 Mar 2021 14:08:36 -0700 Subject: [PATCH 4/5] docs: update upgrade guidelines for b3 propagation --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 32ccfda003..574f000eab 100644 --- a/README.md +++ b/README.md @@ -247,6 +247,10 @@ To request automatic tracing support for a module not on this list, please [file ## Upgrade guidelines +### 0.18.0 to 0.19.0 + +- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [readme](./packages/opentelemetry-propagator-b3/readme.md) for full details and usage. + ### 0.17.0 to 0.18.0 - `diag.setLogLevel` is removed and LogLevel can be set by an optional second parameter to `setLogger` From 5536cf3bf10e12e817b11435be03d406e5b6ebba Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 30 Mar 2021 14:54:38 -0700 Subject: [PATCH 5/5] docs: fix typos --- README.md | 2 +- packages/opentelemetry-propagator-b3/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 574f000eab..3f3d62ab79 100644 --- a/README.md +++ b/README.md @@ -249,7 +249,7 @@ To request automatic tracing support for a module not on this list, please [file ### 0.18.0 to 0.19.0 -- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [readme](./packages/opentelemetry-propagator-b3/readme.md) for full details and usage. +- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [readme](./packages/opentelemetry-propagator-b3/readme.md) for full details and usage. ### 0.17.0 to 0.18.0 diff --git a/packages/opentelemetry-propagator-b3/README.md b/packages/opentelemetry-propagator-b3/README.md index 5b45b088d5..26ad1c4bba 100644 --- a/packages/opentelemetry-propagator-b3/README.md +++ b/packages/opentelemetry-propagator-b3/README.md @@ -96,7 +96,7 @@ api.propagation.setGlobalPropagator( ### B3 Single and Multi-Header Configuration The B3Propagator always extracts both the single and multi-header b3 encodings. -If you need to inject both encoding this can accomplished using a composite +If you need to inject both encodings this can accomplished using a composite propagator. ```javascript