refactor: simplify b3 options (#2054)

Co-authored-by: Valentin Marchaud <[email protected]>

Author: mwear

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`

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)

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 }),
+    ],
   })
 );
 ```

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]);
 

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';
 
 /**

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']);

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';

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';

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', () => {

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;