chore: add fields operation to TextMapPropagator

packages/opentelemetry-api/src/context/propagation/NoopTextMapPropagator.ts

@@ -27,6 +27,9 @@ export class NoopTextMapPropagator implements TextMapPropagator {
   extract(context: Context, carrier: unknown): Context {
     return context;
   }
+  fields(): string[] {
+    return [];
+  }
 }
 
 export const NOOP_TEXT_MAP_PROPAGATOR = new NoopTextMapPropagator();

packages/opentelemetry-api/src/context/propagation/TextMapPropagator.ts

@@ -64,6 +64,14 @@ export interface TextMapPropagator<Carrier = any> {
     carrier: Carrier,
     getter: TextMapGetter<Carrier>
   ): Context;
+
+  /**
+   * Return a list of all fields which may be used by the propagator.
+   *
+   * This list should be used to clear fields before calling inject if a carrier is
+   * used more than once.
+   */
+  fields(): string[];
 }
 
 /**

packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts

@@ -128,4 +128,8 @@ export class HttpTraceContext implements TextMapPropagator {
     }
     return setExtractedSpanContext(context, spanContext);
   }
+
+  fields(): string[] {
+    return [TRACE_PARENT_HEADER, TRACE_STATE_HEADER];
+  }
 }

packages/opentelemetry-core/src/context/propagation/composite.ts

@@ -28,6 +28,7 @@ import { CompositePropagatorConfig } from './types';
 export class CompositePropagator implements TextMapPropagator {
   private readonly _propagators: TextMapPropagator[];
   private readonly _logger: Logger;
+  private readonly _fields: string[];
 
   /**
    * Construct a composite propagator from a list of propagators.
@@ -37,6 +38,14 @@ export class CompositePropagator implements TextMapPropagator {
   constructor(config: CompositePropagatorConfig = {}) {
     this._propagators = config.propagators ?? [];
     this._logger = config.logger ?? new NoopLogger();
+    this._fields = Array.from(
+      new Set(
+        this._propagators
+          // older propagators may not have fields function, null check to be sure
+          .map(p => (typeof p.fields === 'function' ? p.fields() : []))
+          .reduce((x, y) => x.concat(y))
+      )
+    );
   }
 
   /**
@@ -81,4 +90,9 @@ export class CompositePropagator implements TextMapPropagator {
       return ctx;
     }, context);
   }
+
+  fields(): string[] {
+    // return a new array so our fields cannot be modified
+    return this._fields.slice();
+  }
 }

packages/opentelemetry-core/src/correlation-context/propagation/HttpCorrelationContext.ts

@@ -118,4 +118,8 @@ export class HttpCorrelationContext implements TextMapPropagator {
     }
     return { key, value };
   }
+
+  fields(): string[] {
+    return [CORRELATION_CONTEXT_HEADER];
+  }
 }

packages/opentelemetry-core/test/context/HttpTraceContext.test.ts

@@ -289,4 +289,11 @@ describe('HttpTraceContext', () => {
       assert.ok(ctx3 === ROOT_CONTEXT);
     });
   });
+
+  describe('fields()', () => {
+    it('should return fields used by trace context', () => {
+      const fields = httpTraceContext.fields();
+      assert.deepStrictEqual(fields, [TRACE_PARENT_HEADER, TRACE_STATE_HEADER]);
+    });
+  });
 });

packages/opentelemetry-core/test/context/composite.test.ts

@@ -147,6 +147,68 @@ describe('Composite Propagator', () => {
       assert.strictEqual(spanContext.traceState!.get('foo'), 'bar');
     });
   });
+
+  describe('fields()', () => {
+    it('should combine fields from both propagators', () => {
+      const composite = new CompositePropagator({
+        propagators: [
+          {
+            extract: c => c,
+            inject: () => {},
+            fields: () => ['p1'],
+          },
+          {
+            extract: c => c,
+            inject: () => {},
+            fields: () => ['p2'],
+          },
+        ],
+      });
+
+      assert.deepStrictEqual(composite.fields(), ['p1', 'p2']);
+    });
+
+    it('should ignore propagators without fields function', () => {
+      const composite = new CompositePropagator({
+        propagators: [
+          {
+            extract: c => c,
+            inject: () => {},
+            fields: () => ['p1'],
+          },
+          // @ts-expect-error
+          {
+            extract: c => c,
+            inject: () => {},
+          },
+        ],
+      });
+
+      assert.deepStrictEqual(composite.fields(), ['p1']);
+    });
+
+    it('should not allow caller to modify fields', () => {
+      const composite = new CompositePropagator({
+        propagators: [
+          {
+            extract: c => c,
+            inject: () => {},
+            fields: () => ['p1'],
+          },
+          {
+            extract: c => c,
+            inject: () => {},
+            fields: () => ['p2'],
+          },
+        ],
+      });
+
+      const fields = composite.fields();
+      assert.deepStrictEqual(fields, ['p1', 'p2']);
+      fields[1] = 'p3';
+      assert.deepStrictEqual(composite.fields(), ['p1', 'p2']);
+    });
+  });
 });
 
 class ThrowingPropagator implements TextMapPropagator {
@@ -157,4 +219,8 @@ class ThrowingPropagator implements TextMapPropagator {
   extract(context: Context, carrier: unknown): Context {
     throw new Error('This propagator throws');
   }
+
+  fields(): string[] {
+    return [];
+  }
 }

packages/opentelemetry-core/test/correlation-context/HttpCorrelationContext.test.ts

@@ -127,6 +127,13 @@ describe('HttpCorrelationContext', () => {
     });
   });
 
+  describe('fields()', () => {
+    it('returns the fields used by the baggage spec', () => {
+      const propagator = new HttpCorrelationContext();
+      assert.deepStrictEqual(propagator.fields(), [CORRELATION_CONTEXT_HEADER]);
+    });
+  });
+
   it('returns undefined if header is missing', () => {
     assert.deepStrictEqual(
       getCorrelationContext(

packages/opentelemetry-plugin-http/test/utils/DummyPropagation.ts

@@ -43,4 +43,10 @@ export class DummyPropagation implements TextMapPropagator {
     headers[DummyPropagation.TRACE_CONTEXT_KEY] = spanContext.traceId;
     headers[DummyPropagation.SPAN_CONTEXT_KEY] = spanContext.spanId;
   }
+  fields(): string[] {
+    return [
+      DummyPropagation.TRACE_CONTEXT_KEY,
+      DummyPropagation.SPAN_CONTEXT_KEY,
+    ];
+  }
 }

packages/opentelemetry-plugin-https/test/utils/DummyPropagation.ts

@@ -43,4 +43,10 @@ export class DummyPropagation implements TextMapPropagator {
     headers[DummyPropagation.TRACE_CONTEXT_KEY] = spanContext.traceId;
     headers[DummyPropagation.SPAN_CONTEXT_KEY] = spanContext.spanId;
   }
+  fields(): string[] {
+    return [
+      DummyPropagation.TRACE_CONTEXT_KEY,
+      DummyPropagation.SPAN_CONTEXT_KEY,
+    ];
+  }
 }

packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts

@@ -138,4 +138,14 @@ export class B3MultiPropagator implements TextMapPropagator {
     }
     return context;
   }
+
+  fields(): string[] {
+    return [
+      X_B3_TRACE_ID,
+      X_B3_SPAN_ID,
+      X_B3_FLAGS,
+      X_B3_SAMPLED,
+      X_B3_PARENT_SPAN_ID,
+    ];
+  }
 }

packages/opentelemetry-propagator-b3/src/B3Propagator.ts

@@ -39,12 +39,15 @@ export class B3Propagator implements TextMapPropagator {
     carrier: unknown,
     setter: TextMapSetter
   ) => void;
+  public readonly _fields: string[];
 
   constructor(config: B3PropagatorConfig = {}) {
     if (config.injectEncoding === B3InjectEncoding.MULTI_HEADER) {
       this._inject = this._b3MultiPropagator.inject;
+      this._fields = this._b3MultiPropagator.fields();
     } else {
       this._inject = this._b3SinglePropagator.inject;
+      this._fields = this._b3SinglePropagator.fields();
     }
   }
 
@@ -59,4 +62,8 @@ export class B3Propagator implements TextMapPropagator {
       return this._b3MultiPropagator.extract(context, carrier, getter);
     }
   }
+
+  fields(): string[] {
+    return this._fields;
+  }
 }

packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts

@@ -88,4 +88,8 @@ export class B3SinglePropagator implements TextMapPropagator {
       traceFlags,
     });
   }
+
+  fields(): string[] {
+    return [B3_CONTEXT_HEADER];
+  }
 }

packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts

@@ -28,6 +28,8 @@ import { B3Propagator } from '../src/B3Propagator';
 import { B3InjectEncoding } from '../src/types';
 import { B3_CONTEXT_HEADER } from '../src/B3SinglePropagator';
 import {
+  X_B3_FLAGS,
+  X_B3_PARENT_SPAN_ID,
   X_B3_SAMPLED,
   X_B3_SPAN_ID,
   X_B3_TRACE_ID,
@@ -148,4 +150,23 @@ describe('B3Propagator', () => {
       });
     });
   });
+
+  describe('fields()', () => {
+    it('returns single header field by default', () => {
+      const propagator = new B3Propagator();
+      assert.deepStrictEqual(propagator.fields(), [B3_CONTEXT_HEADER]);
+    });
+    it('returns multi fields when configured to use multi fields', () => {
+      const propagator = new B3Propagator({
+        injectEncoding: B3InjectEncoding.MULTI_HEADER,
+      });
+      assert.deepStrictEqual(propagator.fields(), [
+        X_B3_TRACE_ID,
+        X_B3_SPAN_ID,
+        X_B3_FLAGS,
+        X_B3_SAMPLED,
+        X_B3_PARENT_SPAN_ID,
+      ]);
+    });
+  });
 });