Skip to content

Commit d4d3732

Browse files
trentmtrentm
authored
feat(instrumentation): export generic 'semconvStabilityFromStr()' utility, rather than namespace-specific ones (#5684)
1 parent 56610a0 commit d4d3732

File tree

10 files changed

+141
-109
lines changed

10 files changed

+141
-109
lines changed

‎experimental/CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
1414
* Configure the instrumentation with `semconvStabilityOptIn: 'http'` to use the new, stable semconv v1.23.1 semantics or `'http/dup'` for both old (v1.7.0) and stable semantics. When `semconvStabilityOptIn` is not specified (or does not contain these values), it uses the old semconv v1.7.0. I.e. the default behavior is unchanged.
1515
* feat(instrumentation-fetch): support migration to stable HTTP semconv, v1.23.1 [#5651](https://github.com/open-telemetry/opentelemetry-js/pull/5651) @trentm
1616
* Configure the instrumentation with `semconvStabilityOptIn: 'http'` to use the new, stable semconv v1.23.1 semantics or `'http/dup'` for both old (v1.7.0) and stable semantics. When `semconvStabilityOptIn` is not specified (or does not contain these values), it uses the old semconv v1.7.0. I.e. the default behavior is unchanged.
17-
* feat(instrumentation): New utilities for semconv stability migration for instrumentations that produce 'http' and 'db' telemetry. [#5659](https://github.com/open-telemetry/opentelemetry-js/pull/5659) @trentm
18-
* See [semconv stability usage guide](./packages/opentelemetry-instrumentation/src/semconvStability.ts).
17+
* feat(instrumentation): New `semconvStabilityFromStr()` utility for semconv stability migration in instrumentations. [#5684](https://github.com/open-telemetry/opentelemetry-js/pull/5684) @trentm
18+
* See [the utility comment](https://github.com/trentm/opentelemetry-js/blob/main/experimental/packages/opentelemetry-instrumentation/src/semconvStability.ts).
1919
* feat(instrumentation-grpc): support migration to stable HTTP semconv [#5653](https://github.com/open-telemetry/opentelemetry-js/pull/5653) @JamieDanielson
2020
* feat(instrumentation-http): capture synthetic source type on requests [#5488](https://github.com/open-telemetry/opentelemetry-js/pull/5488) @JacksonWeber
2121

‎experimental/packages/opentelemetry-instrumentation-fetch/src/fetch.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
import * as api from '@opentelemetry/api';
1818
import {
1919
SemconvStability,
20-
httpSemconvStabilityFromStr,
20+
semconvStabilityFromStr,
2121
isWrapped,
2222
InstrumentationBase,
2323
InstrumentationConfig,
@@ -118,7 +118,8 @@ export class FetchInstrumentation extends InstrumentationBase<FetchInstrumentati
118118

119119
constructor(config: FetchInstrumentationConfig = {}) {
120120
super('@opentelemetry/instrumentation-fetch', VERSION, config);
121-
this._semconvStability = httpSemconvStabilityFromStr(
121+
this._semconvStability = semconvStabilityFromStr(
122+
'http',
122123
config?.semconvStabilityOptIn
123124
);
124125
}

‎experimental/packages/opentelemetry-instrumentation-fetch/test/fetch.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
import * as api from '@opentelemetry/api';
1818
import {
1919
SemconvStability,
20-
httpSemconvStabilityFromStr,
20+
semconvStabilityFromStr,
2121
isWrapped,
2222
registerInstrumentations,
2323
} from '@opentelemetry/instrumentation';
@@ -1250,7 +1250,8 @@ describe('fetch', () => {
12501250
) => {
12511251
const span: tracing.ReadableSpan = exportedSpans[0];
12521252

1253-
const semconvStability = httpSemconvStabilityFromStr(
1253+
const semconvStability = semconvStabilityFromStr(
1254+
'http',
12541255
config.semconvStabilityOptIn
12551256
);
12561257
if (semconvStability & SemconvStability.OLD) {

‎experimental/packages/opentelemetry-instrumentation-grpc/src/instrumentation.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ import {
5555
InstrumentationNodeModuleDefinition,
5656
InstrumentationBase,
5757
SemconvStability,
58-
httpSemconvStabilityFromStr,
58+
semconvStabilityFromStr,
5959
} from '@opentelemetry/instrumentation';
6060

6161
import {
@@ -103,7 +103,8 @@ export class GrpcInstrumentation extends InstrumentationBase<GrpcInstrumentation
103103
super('@opentelemetry/instrumentation-grpc', VERSION, config);
104104
this._metadataCapture = this._createMetadataCapture();
105105

106-
this._semconvStability = httpSemconvStabilityFromStr(
106+
this._semconvStability = semconvStabilityFromStr(
107+
'http',
107108
process.env.OTEL_SEMCONV_STABILITY_OPT_IN
108109
);
109110
}

‎experimental/packages/opentelemetry-instrumentation-http/src/http.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ import {
4848
InstrumentationBase,
4949
InstrumentationNodeModuleDefinition,
5050
SemconvStability,
51-
httpSemconvStabilityFromStr,
51+
semconvStabilityFromStr,
5252
safeExecuteInTheMiddle,
5353
} from '@opentelemetry/instrumentation';
5454
import { errorMonitor } from 'events';
@@ -100,7 +100,8 @@ export class HttpInstrumentation extends InstrumentationBase<HttpInstrumentation
100100
constructor(config: HttpInstrumentationConfig = {}) {
101101
super('@opentelemetry/instrumentation-http', VERSION, config);
102102
this._headerCapture = this._createHeaderCapture();
103-
this._semconvStability = httpSemconvStabilityFromStr(
103+
this._semconvStability = semconvStabilityFromStr(
104+
'http',
104105
process.env.OTEL_SEMCONV_STABILITY_OPT_IN
105106
);
106107
}

‎experimental/packages/opentelemetry-instrumentation-xml-http-request/src/xhr.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
import * as api from '@opentelemetry/api';
1818
import {
1919
SemconvStability,
20-
httpSemconvStabilityFromStr,
20+
semconvStabilityFromStr,
2121
isWrapped,
2222
InstrumentationBase,
2323
InstrumentationConfig,
@@ -122,7 +122,8 @@ export class XMLHttpRequestInstrumentation extends InstrumentationBase<XMLHttpRe
122122

123123
constructor(config: XMLHttpRequestInstrumentationConfig = {}) {
124124
super('@opentelemetry/instrumentation-xml-http-request', VERSION, config);
125-
this._semconvStability = httpSemconvStabilityFromStr(
125+
this._semconvStability = semconvStabilityFromStr(
126+
'http',
126127
config?.semconvStabilityOptIn
127128
);
128129
}

‎experimental/packages/opentelemetry-instrumentation-xml-http-request/test/xhr.test.ts‎

Lines changed: 27 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import { otperformance as performance } from '@opentelemetry/core';
1818
import {
1919
registerInstrumentations,
2020
isWrapped,
21-
httpSemconvStabilityFromStr,
21+
semconvStabilityFromStr,
2222
SemconvStability,
2323
} from '@opentelemetry/instrumentation';
2424
import {
@@ -431,7 +431,8 @@ describe('xhr', () => {
431431
const span: tracing.ReadableSpan = exportSpy.args[1][0][0];
432432
const attributes = span.attributes;
433433
let expectedNumAttrs = 0;
434-
const semconvStability = httpSemconvStabilityFromStr(
434+
const semconvStability = semconvStabilityFromStr(
435+
'http',
435436
test.semconvStabilityOptIn
436437
);
437438

@@ -897,7 +898,8 @@ describe('xhr', () => {
897898
const span: tracing.ReadableSpan = exportSpy.args[0][0][0];
898899
const attributes = span.attributes;
899900

900-
const semconvStability = httpSemconvStabilityFromStr(
901+
const semconvStability = semconvStabilityFromStr(
902+
'http',
901903
test.semconvStabilityOptIn
902904
);
903905

@@ -934,7 +936,8 @@ describe('xhr', () => {
934936
it('should still add the CONTENT_LENGTH attribute', () => {
935937
const span: tracing.ReadableSpan = exportSpy.args[1][0][0];
936938
const attributes = span.attributes;
937-
const semconvStability = httpSemconvStabilityFromStr(
939+
const semconvStability = semconvStabilityFromStr(
940+
'http',
938941
test.semconvStabilityOptIn
939942
);
940943

@@ -1110,7 +1113,8 @@ describe('xhr', () => {
11101113
const span: tracing.ReadableSpan = exportSpy.args[0][0][0];
11111114
const attributes = span.attributes;
11121115
let expectedNumAttrs = 0;
1113-
const semconvStability = httpSemconvStabilityFromStr(
1116+
const semconvStability = semconvStabilityFromStr(
1117+
'http',
11141118
test.semconvStabilityOptIn
11151119
);
11161120

@@ -1233,7 +1237,8 @@ describe('xhr', () => {
12331237
const attributes = span.attributes;
12341238

12351239
let expectedNumAttrs = 0;
1236-
const semconvStability = httpSemconvStabilityFromStr(
1240+
const semconvStability = semconvStabilityFromStr(
1241+
'http',
12371242
test.semconvStabilityOptIn
12381243
);
12391244

@@ -1353,7 +1358,8 @@ describe('xhr', () => {
13531358
const attributes = span.attributes;
13541359

13551360
let expectedNumAttrs = 0;
1356-
const semconvStability = httpSemconvStabilityFromStr(
1361+
const semconvStability = semconvStabilityFromStr(
1362+
'http',
13571363
test.semconvStabilityOptIn
13581364
);
13591365

@@ -1471,7 +1477,8 @@ describe('xhr', () => {
14711477
const attributes = span.attributes;
14721478

14731479
let expectedNumAttrs = 0;
1474-
const semconvStability = httpSemconvStabilityFromStr(
1480+
const semconvStability = semconvStabilityFromStr(
1481+
'http',
14751482
test.semconvStabilityOptIn
14761483
);
14771484

@@ -1818,7 +1825,8 @@ describe('xhr', () => {
18181825
const attributes = span.attributes;
18191826

18201827
let expectedNumAttrs = 0;
1821-
const semconvStability = httpSemconvStabilityFromStr(
1828+
const semconvStability = semconvStabilityFromStr(
1829+
'http',
18221830
test.semconvStabilityOptIn
18231831
);
18241832

@@ -2288,7 +2296,8 @@ describe('xhr', () => {
22882296
const span: tracing.ReadableSpan = exportSpy.args[0][0][0];
22892297
const attributes = span.attributes;
22902298

2291-
const semconvStability = httpSemconvStabilityFromStr(
2299+
const semconvStability = semconvStabilityFromStr(
2300+
'http',
22922301
test.semconvStabilityOptIn
22932302
);
22942303

@@ -2480,7 +2489,8 @@ describe('xhr', () => {
24802489
const attributes = span.attributes;
24812490

24822491
let expectedNumAttrs = 0;
2483-
const semconvStability = httpSemconvStabilityFromStr(
2492+
const semconvStability = semconvStabilityFromStr(
2493+
'http',
24842494
test.semconvStabilityOptIn
24852495
);
24862496

@@ -2602,7 +2612,8 @@ describe('xhr', () => {
26022612
const attributes = span.attributes;
26032613

26042614
let expectedNumAttrs = 0;
2605-
const semconvStability = httpSemconvStabilityFromStr(
2615+
const semconvStability = semconvStabilityFromStr(
2616+
'http',
26062617
test.semconvStabilityOptIn
26072618
);
26082619

@@ -2720,7 +2731,8 @@ describe('xhr', () => {
27202731
const attributes = span.attributes;
27212732

27222733
let expectedNumAttrs = 0;
2723-
const semconvStability = httpSemconvStabilityFromStr(
2734+
const semconvStability = semconvStabilityFromStr(
2735+
'http',
27242736
test.semconvStabilityOptIn
27252737
);
27262738

@@ -2838,7 +2850,8 @@ describe('xhr', () => {
28382850
const attributes = span.attributes;
28392851

28402852
let expectedNumAttrs = 0;
2841-
const semconvStability = httpSemconvStabilityFromStr(
2853+
const semconvStability = semconvStabilityFromStr(
2854+
'http',
28422855
test.semconvStabilityOptIn
28432856
);
28442857

‎experimental/packages/opentelemetry-instrumentation/src/index.ts‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,4 @@ export {
3232
safeExecuteInTheMiddle,
3333
safeExecuteInTheMiddleAsync,
3434
} from './utils';
35-
export {
36-
SemconvStability,
37-
httpSemconvStabilityFromStr,
38-
databaseSemconvStabilityFromStr,
39-
} from './semconvStability';
35+
export { SemconvStability, semconvStabilityFromStr } from './semconvStability';

‎experimental/packages/opentelemetry-instrumentation/src/semconvStability.ts‎

Lines changed: 40 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -14,32 +14,56 @@
1414
* limitations under the License.
1515
*/
1616

17+
export const enum SemconvStability {
18+
/** Emit only stable semantic conventions. */
19+
STABLE = 0x1,
20+
/** Emit only old semantic conventions. */
21+
OLD = 0x2,
22+
/** Emit both stable and old semantic conventions. */
23+
DUPLICATE = 0x1 | 0x2,
24+
}
25+
26+
// Common namespaces mentioned in semantic-conventions docs, but allow
27+
// other custom strings.
28+
type SemConvStabilityNamespace =
29+
| 'http'
30+
| 'messaging'
31+
| 'database'
32+
| 'k8s'
33+
| (string & {});
34+
1735
/**
18-
* This file holds utilities for semconv stability migration, as described at:
19-
* - https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
20-
* - https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/
36+
* Determine the appropriate semconv stability for the given namespace.
2137
*
22-
* The intent is that these exports will be *removed* in the next breaking
23-
* release after the semconv migration of relevant packages from
24-
* opentelemetry-js.git and opentelemetry-js-contrib.git is complete.
38+
* This will parse the given string of comma-separated values (often
39+
* `process.env.OTEL_SEMCONV_STABILITY_OPT_IN`) looking for the `${namespace}`
40+
* or `${namespace}/dup` tokens. This is a pattern defined by a number of
41+
* non-normative semconv documents.
42+
*
43+
* For example:
44+
* - namespace 'http': https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
45+
* - namespace 'database': https://opentelemetry.io/docs/specs/semconv/non-normative/database-migration/
46+
* - namespace 'k8s': https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-migration/
2547
*
2648
* Usage:
2749
*
28-
* import {SemconvStability, httpSemconvStabilityFromStr} from '@opentelemetry/instrumentation';
50+
* import {SemconvStability, semconvStabilityFromStr} from '@opentelemetry/instrumentation';
2951
*
30-
* export class FooInstrumentation extends InstrumentationBase<MyInstrumentationConfig> {
52+
* export class FooInstrumentation extends InstrumentationBase<FooInstrumentationConfig> {
3153
* private _semconvStability: SemconvStability;
3254
* constructor(config: FooInstrumentationConfig = {}) {
3355
* super('@opentelemetry/instrumentation-foo', VERSION, config);
3456
*
3557
* // When supporting the OTEL_SEMCONV_STABILITY_OPT_IN envvar
36-
* this._semconvStability = httpSemconvStabilityFromStr(
58+
* this._semconvStability = semconvStabilityFromStr(
59+
* 'http',
3760
* process.env.OTEL_SEMCONV_STABILITY_OPT_IN
3861
* );
3962
*
4063
* // or when supporting a `semconvStabilityOptIn` config option (e.g. for
4164
* // the web where there are no envvars).
42-
* this._semconvStability = httpSemconvStabilityFromStr(
65+
* this._semconvStability = semconvStabilityFromStr(
66+
* 'http',
4367
* config?.semconvStabilityOptIn
4468
* );
4569
* }
@@ -54,17 +78,10 @@
5478
* }
5579
*
5680
*/
57-
58-
export const enum SemconvStability {
59-
/** Emit only stable semantic conventions. */
60-
STABLE = 0x1,
61-
/** Emit only old semantic conventions. */
62-
OLD = 0x2,
63-
/** Emit both stable and old semantic conventions. */
64-
DUPLICATE = 0x1 | 0x2,
65-
}
66-
67-
function _semconvStabilityFromStr(marker: string, str: string | undefined) {
81+
export function semconvStabilityFromStr(
82+
namespace: SemConvStabilityNamespace,
83+
str: string | undefined
84+
) {
6885
let semconvStability = SemconvStability.OLD;
6986

7087
// The same parsing of `str` as `getStringListFromEnv` from the core pkg.
@@ -73,36 +90,14 @@ function _semconvStabilityFromStr(marker: string, str: string | undefined) {
7390
.map(v => v.trim())
7491
.filter(s => s !== '');
7592
for (const entry of entries ?? []) {
76-
if (entry.toLowerCase() === marker + '/dup') {
93+
if (entry.toLowerCase() === namespace + '/dup') {
7794
// DUPLICATE takes highest precedence.
7895
semconvStability = SemconvStability.DUPLICATE;
7996
break;
80-
} else if (entry.toLowerCase() === marker) {
97+
} else if (entry.toLowerCase() === namespace) {
8198
semconvStability = SemconvStability.STABLE;
8299
}
83100
}
84101

85102
return semconvStability;
86103
}
87-
88-
/**
89-
* Determine appropriate 'http' semconv stability per
90-
* https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
91-
*
92-
* Note: This method will be removed after OTel JS HTTP semconv migration is
93-
* complete (https://github.com/open-telemetry/opentelemetry-js/issues/5646).
94-
*/
95-
export function httpSemconvStabilityFromStr(str: string | undefined) {
96-
return _semconvStabilityFromStr('http', str);
97-
}
98-
99-
/**
100-
* Determine appropriate 'database' semconv stability per
101-
* https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/
102-
*
103-
* Note: This method will be removed after OTel JS DB semconv migration is
104-
* complete (https://github.com/open-telemetry/opentelemetry-js/issues/5658).
105-
*/
106-
export function databaseSemconvStabilityFromStr(str: string | undefined) {
107-
return _semconvStabilityFromStr('database', str);
108-
}

0 commit comments

Comments
 (0)