Skip to content

Commit

Permalink
doc(instrumentation): add limitiations section to readme (#3786)
Browse files Browse the repository at this point in the history
Co-authored-by: Marc Pichler <marc.pichler@dynatrace.com>
  • Loading branch information
Flarna and pichlermarc authored May 11, 2023
1 parent b8b6308 commit 32632bd
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 59 deletions.
2 changes: 2 additions & 0 deletions experimental/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ All notable changes to experimental packages in this project will be documented

### :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
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

0 comments on commit 32632bd

Please sign in to comment.