Skip to content

Commit

Permalink
Merge branch 'main' into release/1.13-0.39
Browse files Browse the repository at this point in the history
  • Loading branch information
pichlermarc committed May 11, 2023
2 parents 974b507 + 32632bd commit 666bb2a
Show file tree
Hide file tree
Showing 16 changed files with 451 additions and 67 deletions.
6 changes: 6 additions & 0 deletions experimental/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ All notable changes to experimental packages in this project will be documented
* fix(instrumentation): update `require-in-the-middle` to v7.1.0 [#3727](https://github.com/open-telemetry/opentelemetry-js/pull/3727) @trentm
* fix(instrumentation): update `require-in-the-middle` to v7.0.1 [#3743](https://github.com/open-telemetry/opentelemetry-js/pull/3743) @trentm

### :books: (Refine Doc)

* doc(instrumentation): add limitiations section to readme [#3786](https://github.com/open-telemetry/opentelemetry-js/pull/3786) @flarna

### :house: (Internal)

## 0.38.0

### :boom: Breaking Change
Expand Down
82 changes: 23 additions & 59 deletions experimental/packages/opentelemetry-instrumentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ import {

import type * as module_name_to_be_patched from 'module_name_to_be_patched';

export class MyPlugin extends InstrumentationBase {
export class MyInstrumentation extends InstrumentationBase {
constructor(config: InstrumentationConfig = {}) {
super('MyPlugin', VERSION, config);
super('MyInstrumentation', VERSION, config);
}

/**
Expand Down Expand Up @@ -106,12 +106,12 @@ export class MyPlugin extends InstrumentationBase {
}
}

// Later
// Later, but before the module to instrument is required

const myPLugin = new MyPlugin();
myPLugin.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
myPLugin.setMeterProvider(meterProvider); // this is optional
myPLugin.enable();
const myInstrumentationn = new MyInstrumentation();
myInstrumentation.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
myInstrumentation.setMeterProvider(meterProvider); // this is optional
myInstrumentation.enable();
// or use Auto Loader
```

Expand All @@ -125,9 +125,9 @@ import {

import { Instrumentation } from '@opentelemetry/instrumentation';

export class MyPlugin extends InstrumentationBase {
export class MyInstrumentation extends InstrumentationBase {
constructor(config: InstrumentationConfig = {}) {
super('MyPlugin', VERSION, config);
super('MyInstrumentation', VERSION, config);
}

private _patchOpen() {
Expand All @@ -150,59 +150,15 @@ export class MyPlugin extends InstrumentationBase {

// Later

const myPLugin = new MyPlugin();
myPLugin.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
myPLugin.setMeterProvider(meterProvider); // this is optional, only if global MeterProvider shouldn't be used
myPLugin.enable();
const myInstrumentation = new MyInstrumentation();
myInstrumentation.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
myInstrumentation.setMeterProvider(meterProvider); // this is optional, only if global MeterProvider shouldn't be used
myInstrumentation.enable();
// or use Auto Loader
```

## AutoLoader

Successor of loading plugins through TracerProvider "plugins" option.
It also supersedes PluginLoader for node. The old configurations usually looks like

### NODE - old way using TracerProvider - not available anymore

```javascript
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
const provider = new NodeTracerProvider({
plugins: {
http: { enabled: false },
},
});
provider.register({
propagator: new B3Propagator(),
});
```

### WEB - old way using TracerProvider - not available anymore

```javascript
const { WebTracerProvider } = require('@opentelemetry/sdk-trace-web');
const { UserInteractionPlugin } = require('@opentelemetry/plugin-user-interaction');
const { XMLHttpRequestInstrumentation } = require('@opentelemetry/instrumentation-xml-http-request');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
const provider = new WebTracerProvider({
plugins: [
new UserInteractionPlugin(),
new XMLHttpRequestInstrumentation({
ignoreUrls: [/localhost/],
propagateTraceHeaderCorsUrls: [
'http://localhost:8090',
],
}),
],
});
provider.register({
propagator: new B3Propagator(),
});
```

After change it will look like this - mixing plugins and instrumentations together
All plugins will be bound to TracerProvider as well as instrumentations

### NODE - Auto Loader

```javascript
Expand Down Expand Up @@ -263,14 +219,22 @@ If nothing is specified the global registered provider is used. Usually this is
There might be usecase where someone has the need for more providers within an application. Please note that special care must be takes in such setups
to avoid leaking information from one provider to the other because there are a lot places where e.g. the global `ContextManager` or `Propagator` is used.

## Limitations

Instrumentations for external modules (e.g. express, mongodb,...) hooks the `require` call. Therefore following conditions need to be met that this mechanism can work:

* `require` is used. ECMA script modules (using `import`) is not supported as of now
* Instrumentations are registered **before** the module to instrument is `require`ed
* modules are not included in a bundle. Tools like `esbuild`, `webpack`, ... usually have some mechanism to exclude specific modules from bundling

## License

Apache 2.0 - See [LICENSE][license-url] for more information.

## Useful links

- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
* For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
* For help or feedback on this project, join us in [GitHub Discussions][discussions-url]

[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"prepublishOnly": "npm run compile",
"compile": "tsc --build",
"clean": "tsc --build --clean",
"tdd": "npm run test -- --extension ts --watch",
"test": "nyc ts-mocha -p tsconfig.json test/**/*.test.ts",
"codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../../",
"lint": "eslint . --ext .ts",
Expand Down Expand Up @@ -44,28 +45,30 @@
"access": "public"
},
"devDependencies": {
"@opentelemetry/core": "1.13.0",
"@opentelemetry/context-async-hooks": "1.13.0",
"@opencensus/core": "0.1.0",
"@opentelemetry/api": ">=1.0.0 <1.5.0",
"@opentelemetry/context-async-hooks": "1.11.0",
"@opentelemetry/core": "1.11.0",
"@opentelemetry/api": "1.4.1",
"@types/mocha": "10.0.0",
"@types/node": "18.6.5",
"codecov": "3.8.3",
"mocha": "10.0.0",
"nyc": "15.1.0",
"sinon": "15.0.0",
"@types/sinon": "10.0.13",
"ts-mocha": "10.0.0",
"typescript": "4.4.4"
},
"peerDependencies": {
"@opencensus/core": "^0.1.0",
"@opentelemetry/api": ">=1.0.0 <1.5.0"
"@opentelemetry/api": "^1.0.0"
},
"dependencies": {
"@opentelemetry/context-async-hooks": "1.13.0",
"@opentelemetry/core": "1.13.0",
"require-in-the-middle": "^6.0.0",
"semver": "^7.3.5"
},
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-shim-opencensus",
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/shim-opencensus",
"sideEffects": false
}
78 changes: 78 additions & 0 deletions experimental/packages/shim-opencensus/src/propagation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
/*
* 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.
*/

import * as oc from '@opencensus/core';

import {
context,
propagation,
trace,
TextMapGetter,
TextMapSetter,
} from '@opentelemetry/api';
import { mapSpanContext, reverseMapSpanContext } from './transform';

class Getter implements TextMapGetter<void> {
constructor(private ocGetter: oc.HeaderGetter) {}
keys(): string[] {
return [];
}
get(carrier: void, key: string) {
return this.ocGetter.getHeader(key);
}
}

class Setter implements TextMapSetter<void> {
constructor(private ocSetter: oc.HeaderSetter) {}
set(carrier: void, key: string, value: string): void {
this.ocSetter.setHeader(key, value);
}
}

/**
* Bridges OpenTelemetry propagation API into OpenCensus. The global OTel propagator is called
* to implement the OpenCensus propagation API.
*/
export const shimPropagation: oc.Propagation = {
extract(getter: oc.HeaderGetter): oc.SpanContext | null {
const extracted = propagation.extract(
context.active(),
null,
new Getter(getter)
);

const otelSc = trace.getSpanContext(extracted);
return otelSc ? reverseMapSpanContext(otelSc) : null;
},

inject(setter: oc.HeaderSetter, spanContext: oc.SpanContext): void {
const ctx = trace.setSpanContext(
context.active(),
mapSpanContext(spanContext)
);
propagation.inject(ctx, null, new Setter(setter));
},

generate(): oc.SpanContext {
// Reading OpenCensus code, it looks like this should generate a new random span context.
// However, it doesn't appear to be used based on my testing. Options for implementing:
//
// - Return the invalid span context
// - Use the OTel ID generator, however this package should be an API-only bridge
// - Copy implementation from OpenCensus noop-propagation.ts
throw new Error('shimPropagation.generate() is not yet implemented');
},
};
105 changes: 105 additions & 0 deletions experimental/packages/shim-opencensus/src/transform.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
/*
* 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.
*/

import * as oc from '@opencensus/core';
import {
Attributes,
SpanContext,
SpanKind,
TimeInput,
diag,
} from '@opentelemetry/api';
import { TraceState } from '@opentelemetry/core';

function exhaust(value: never) {
diag.warn('Could not handle enum value %s', value);
}

export function mapSpanKind(
kind: oc.SpanKind | undefined
): SpanKind | undefined {
switch (kind) {
case undefined:
return undefined;
case oc.SpanKind.UNSPECIFIED:
return SpanKind.INTERNAL;
case oc.SpanKind.CLIENT:
return SpanKind.CLIENT;
case oc.SpanKind.SERVER:
return SpanKind.SERVER;
default:
exhaust(kind);
return undefined;
}
}

export function mapSpanContext({
spanId,
traceId,
options,
traceState,
}: oc.SpanContext): SpanContext {
return {
spanId,
traceId,
traceFlags: options ?? 0,
traceState:
traceState === undefined ? undefined : new TraceState(traceState),
};
}

export function reverseMapSpanContext({
spanId,
traceId,
traceFlags,
traceState,
}: SpanContext): oc.SpanContext {
return {
spanId: spanId,
traceId: traceId,
options: traceFlags,
traceState: traceState?.serialize(),
};
}

// Copied from Java
// https://github.com/open-telemetry/opentelemetry-java/blob/0d3a04669e51b33ea47b29399a7af00012d25ccb/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/SpanConverter.java#L24-L27
const MESSAGE_EVENT_ATTRIBUTE_KEY_TYPE = 'message.event.type';
const MESSAGE_EVENT_ATTRIBUTE_KEY_SIZE_UNCOMPRESSED =
'message.event.size.uncompressed';
const MESSAGE_EVENT_ATTRIBUTE_KEY_SIZE_COMPRESSED =
'message.event.size.compressed';

export function mapMessageEvent(
type: oc.MessageEventType,
id: number,
timestamp?: number,
uncompressedSize?: number,
compressedSize?: number
): [string, Attributes, TimeInput | undefined] {
const attributes: Attributes = {
[MESSAGE_EVENT_ATTRIBUTE_KEY_TYPE]: oc.MessageEventType[type],
};
if (uncompressedSize !== undefined) {
attributes[MESSAGE_EVENT_ATTRIBUTE_KEY_SIZE_UNCOMPRESSED] =
uncompressedSize;
}
if (compressedSize !== undefined) {
attributes[MESSAGE_EVENT_ATTRIBUTE_KEY_SIZE_COMPRESSED] = compressedSize;
}

return [id.toString(), attributes, timestamp];
}
Loading

0 comments on commit 666bb2a

Please sign in to comment.