Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: simplify b3 options #2054

Merged
merged 6 commits into from
Mar 31, 2021
Merged

refactor: simplify b3 options #2054

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
19ba6d2
refactor!: do not export B3SinglePropagator and B3MultiPropagator
mwear Mar 30, 2021
f96861c
docs: update b3 propagator readme
mwear Mar 30, 2021
f9c2bb1
Merge branch 'main' into simplify-b3
vmarchaud Mar 30, 2021
805478e
docs: document b3 composite propagator usage
mwear Mar 30, 2021
3ffd8a1
docs: update upgrade guidelines for b3 propagation
mwear Mar 30, 2021
5536cf3
docs: fix typos
mwear Mar 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions packages/opentelemetry-core/test/context/composite.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ import {
RandomIdGenerator,
} from '../../src';
import {
B3MultiPropagator,
B3Propagator,
B3InjectEncoding,
X_B3_SAMPLED,
X_B3_SPAN_ID,
X_B3_TRACE_ID,
Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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)
Expand Down
63 changes: 5 additions & 58 deletions packages/opentelemetry-propagator-b3/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand All @@ -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');
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is CompositePropagator not allowed anymore, as with regards to possibility I think it should still be possible ?

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

?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By default it already extracts both. Is there a usecase where we need to also inject both? Of course you can always use a composite just like you can with any propagator, but keeping it documented feels unnecessary for such a niche usecase.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure, but we had this before so if anyone is using such case it might be hard to understand how it should be done now after these changes

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's still possible. I don't think it's a common use case, but we can document it.


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: <https://opentelemetry.io/>
Expand Down
14 changes: 7 additions & 7 deletions packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]);

Expand Down
3 changes: 2 additions & 1 deletion packages/opentelemetry-propagator-b3/src/B3Propagator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';

/**
Expand Down
4 changes: 1 addition & 3 deletions packages/opentelemetry-propagator-b3/src/B3SinglePropagator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']);
Expand Down
25 changes: 25 additions & 0 deletions packages/opentelemetry-propagator-b3/src/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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';
3 changes: 1 addition & 2 deletions packages/opentelemetry-propagator-b3/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,5 @@
*/

export * from './B3Propagator';
export * from './B3SinglePropagator';
export * from './B3MultiPropagator';
export * from './constants';
export * from './types';
4 changes: 2 additions & 2 deletions packages/opentelemetry-propagator-b3/test/B3MultiPropagator.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down
4 changes: 2 additions & 2 deletions packages/opentelemetry-propagator-b3/test/B3Propagator.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
6 changes: 2 additions & 4 deletions packages/opentelemetry-propagator-b3/test/B3SinglePropagator.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down