diff --git a/README.md b/README.md index 32ccfda003..3f3d62ab79 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` 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/README.md b/packages/opentelemetry-propagator-b3/README.md index 5748ebc74c..26ad1c4bba 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,53 +93,21 @@ 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`. +### B3 Single and Multi-Header Configuration -Example usage: +The B3Propagator always extracts both the single and multi-header b3 encodings. +If you need to inject both encodings this can accomplished using a composite +propagator. ```javascript const api = require('@opentelemetry/api'); -const { CompositePropagator } = require('@opentelemetry/core'); -const { - B3SinglePropagator, - B3MultiPropagator, -} = require('@opentelemetry/propagator-b3'); - +const { B3Propagator } = require('@opentelemetry/propagator-b3'); api.propagation.setGlobalPropagator( new CompositePropagator({ - propagators: [new B3SinglePropagator(), new B3MultiPropagator()], + propagators: [ + new B3Propagator(), + new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }), + ], }) ); ``` 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', () => {