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.

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

feat: implement W3C Correlation Context propagator #838

Merged
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/*!
* Copyright 2020, 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.
*/

import { CorrelationContext } from '@opentelemetry/api';
import { Context } from '@opentelemetry/context-base';

const CORRELATION_CONTEXT = Context.createKey(
'OpenTelemetry Distributed Contexts Key'
);

export function getCorrelationContext(
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc

context: Context
): CorrelationContext | undefined {
return (
(context.getValue(CORRELATION_CONTEXT) as CorrelationContext) || undefined
);
}

export function setCorrelationContext(
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc

context: Context,
correlationContext: CorrelationContext
): Context {
return context.setValue(CORRELATION_CONTEXT, correlationContext);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
/*!
* Copyright 2020, 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.
*/

import {
Context,
CorrelationContext,
GetterFunction,
HttpTextPropagator,
SetterFunction,
} from '@opentelemetry/api';
import {
getCorrelationContext,
setCorrelationContext,
} from '../correlation-context';

export const CORRELATION_CONTEXT_HEADER = 'otcorrelations';
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc

const KEY_PAIR_SEPARATOR = '=';
const PROPERTIES_SEPARATOR = ';';
const ITEMS_SEPARATOR = ',';

/* W3C Constrains*/

export const MAX_NAME_VALUE_PAIRS = 180;
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc

export const MAX_PER_NAME_VALUE_PAIRS = 4096;
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc

export const MAX_TOTAL_LENGTH = 8192;
Copy link
Member

Choose a reason for hiding this comment

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

missing tsdoc


/**
* Propagates {@link CorrelationContext} through Context format propagation.
*
* Based on the Correlation Context specification:
* https://w3c.github.io/correlation-context/
*/
export class HttpCorrelationContext implements HttpTextPropagator {
mayurkale22 marked this conversation as resolved.
Show resolved Hide resolved
inject(context: Context, carrier: unknown, setter: SetterFunction) {
const correlationContext = getCorrelationContext(context);
if (!correlationContext) return;
const all = Object.keys(correlationContext);
const values = all
Copy link
Member

Choose a reason for hiding this comment

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

Please make an util helper function from this, and the same for values.reduce, it is hard to understand what is happening here, without looking and analysing the code

.map(
(key: string) =>
`${encodeURIComponent(key)}=${encodeURIComponent(
correlationContext[key].value
)}`
)
.filter((pair: string) => {
return pair.length <= MAX_PER_NAME_VALUE_PAIRS;
})
.slice(0, MAX_NAME_VALUE_PAIRS);
const headerValue = values.reduce((hValue: String, current: String) => {
const value = `${hValue}${hValue != '' ? ITEMS_SEPARATOR : ''}${current}`;
return value.length > MAX_TOTAL_LENGTH ? hValue : value;
}, '');
if (headerValue.length > 0) {
setter(carrier, CORRELATION_CONTEXT_HEADER, headerValue);
}
}

extract(context: Context, carrier: unknown, getter: GetterFunction): Context {
const headerValue: string = getter(
carrier,
CORRELATION_CONTEXT_HEADER
) as string;
if (!headerValue) return context;
const correlationContext: CorrelationContext = {};
if (headerValue.length == 0) {
return context;
}
const pairs = headerValue.split(ITEMS_SEPARATOR);
if (pairs.length == 1) return context;
pairs.forEach(entry => {
const valueProps = entry.split(PROPERTIES_SEPARATOR);
Copy link
Member

Choose a reason for hiding this comment

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

consider creating a helper function, maybe a parseHeader or parsePair etc. ?

if (valueProps.length <= 0) return;
const keyPairPart = valueProps.shift();
if (!keyPairPart) return;
const keyPair = keyPairPart.split(KEY_PAIR_SEPARATOR);
if (keyPair.length <= 1) return;
const key = decodeURIComponent(keyPair[0].trim());
let value = decodeURIComponent(keyPair[1].trim());
if (valueProps.length > 0) {
value =
value + PROPERTIES_SEPARATOR + valueProps.join(PROPERTIES_SEPARATOR);
}
correlationContext[key] = { value };
});
return setCorrelationContext(context, correlationContext);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
/*!
* Copyright 2020, 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.
*/

import {
defaultGetter,
defaultSetter,
CorrelationContext,
} from '@opentelemetry/api';
import { Context } from '@opentelemetry/context-base';
import * as assert from 'assert';
import {
getCorrelationContext,
setCorrelationContext,
} from '../../src/correlation-context/correlation-context';
import {
HttpCorrelationContext,
CORRELATION_CONTEXT_HEADER,
MAX_PER_NAME_VALUE_PAIRS,
} from '../../src/correlation-context/propagation/HttpCorrelationContext';

describe('HttpCorrelationContext', () => {
const httpTraceContext = new HttpCorrelationContext();

let carrier: { [key: string]: unknown };

beforeEach(() => {
carrier = {};
});

describe('.inject()', () => {
it('should set correlation context header', () => {
const correlationContext: CorrelationContext = {
key1: { value: 'd4cda95b652f4a1592b449d5929fda1b' },
key3: { value: 'c88815a7-0fa9-4d95-a1f1-cdccce3c5c2a' },
mayurkale22 marked this conversation as resolved.
Show resolved Hide resolved
'with/slash': { value: 'with spaces' },
};

httpTraceContext.inject(
setCorrelationContext(Context.ROOT_CONTEXT, correlationContext),
carrier,
defaultSetter
);
assert.deepStrictEqual(
carrier[CORRELATION_CONTEXT_HEADER],
'key1=d4cda95b652f4a1592b449d5929fda1b,key3=c88815a7-0fa9-4d95-a1f1-cdccce3c5c2a,with%2Fslash=with%20spaces'
);
});

it('should skip long key-value pairs', () => {
const correlationContext: CorrelationContext = {
key1: { value: 'd4cda95b' },
key3: { value: 'c88815a7' },
};

let value = '';
// Generate long value 2*MAX_PER_NAME_VALUE_PAIRS
for (let i = 0; i < MAX_PER_NAME_VALUE_PAIRS; ++i) {
Copy link
Member

Choose a reason for hiding this comment

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

I think it is already safe to use repeat here

value = '1a'.repeat(MAX_PER_NAME_VALUE_PAIRS_);

value += '1a';
}
correlationContext['longPair'] = { value };

httpTraceContext.inject(
setCorrelationContext(Context.ROOT_CONTEXT, correlationContext),
carrier,
defaultSetter
);
assert.deepStrictEqual(
carrier[CORRELATION_CONTEXT_HEADER],
'key1=d4cda95b,key3=c88815a7'
);
});

it('should skip all keys that surpassed the max limit of the header', () => {
const correlationContext: CorrelationContext = {};

const zeroPad = (num: number, places: number) =>
String(num).padStart(places, '0');

// key=value with same size , 1024 => 8 keys
for (let i = 0; i < 9; ++i) {
const index = zeroPad(i, 510);
correlationContext[`k${index}`] = { value: `${index}` };
}

// Build expected
let expected = '';
for (let i = 0; i < 8; ++i) {
const index = zeroPad(i, 510);
expected += `k${index}=${index},`;
}
expected = expected.slice(0, -1);

httpTraceContext.inject(
setCorrelationContext(Context.ROOT_CONTEXT, correlationContext),
carrier,
defaultSetter
);
assert.deepStrictEqual(carrier[CORRELATION_CONTEXT_HEADER], expected);
});
});

describe('.extract()', () => {
it('should extract context of a sampled span from carrier', () => {
carrier[CORRELATION_CONTEXT_HEADER] =
'key1=d4cda95b,key3=c88815a7, keyn = valn, keym =valm';
const extractedCorrelationContext = getCorrelationContext(
httpTraceContext.extract(Context.ROOT_CONTEXT, carrier, defaultGetter)
);

const expected: CorrelationContext = {
key1: { value: 'd4cda95b' },
key3: { value: 'c88815a7' },
keyn: { value: 'valn' },
keym: { value: 'valm' },
};
assert.deepStrictEqual(extractedCorrelationContext, expected);
});
});

it('returns null if header is missing', () => {
Copy link
Member

Choose a reason for hiding this comment

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

it says null, but is being compared against undefined

assert.deepStrictEqual(
getCorrelationContext(
httpTraceContext.extract(Context.ROOT_CONTEXT, carrier, defaultGetter)
),
undefined
);
});

it('returns keys with their properties', () => {
carrier[CORRELATION_CONTEXT_HEADER] =
'key1=d4cda95b,key3=c88815a7;prop1=value1';
const expected: CorrelationContext = {
key1: { value: 'd4cda95b' },
key3: { value: 'c88815a7;prop1=value1' },
};
assert.deepStrictEqual(
getCorrelationContext(
httpTraceContext.extract(Context.ROOT_CONTEXT, carrier, defaultGetter)
),
expected
);
});

it('should gracefully handle an invalid header', () => {
const testCases: Record<string, string> = {
invalidNoKeyValuePair: '289371298nekjh2939299283jbk2b',
invalidDoubleEqual: 'key1==value;key2=value2',
invalidWrongKeyValueFormat: 'key1:value;key2=value2',
invalidDoubleSemicolon: 'key1:value;;key2=value2',
};
Object.getOwnPropertyNames(testCases).forEach(testCase => {
carrier[CORRELATION_CONTEXT_HEADER] = testCases[testCase];

const extractedSpanContext = getCorrelationContext(
httpTraceContext.extract(Context.ROOT_CONTEXT, carrier, defaultGetter)
);
assert.deepStrictEqual(extractedSpanContext, undefined, testCase);
});
});
});