Use instrumentation loader to load plugins and instrumentations

.github/ISSUE_TEMPLATE/request_for_instrumentation.md

@@ -5,9 +5,9 @@ labels: instrumentation
 ---
 
 <!--
-**NB:** Before opening a plugin support request against this repo, consider whether the plugin should reside in the [contrib repository](https://github.com/open-telemetry/opentelemetry-js-contrib).
+**NB:** Before opening an instrumentation support request against this repo, consider whether the instrumentation should reside in the [contrib repository](https://github.com/open-telemetry/opentelemetry-js-contrib).
 
-You are welcome to try out the [plugin api](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/plugin-guide.md) to build your own plugin. If you do try out the plugin api, please let us know if you have any questions/feedback.
+You are welcome to try out the [instrumentation api](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/instrumentation-guide.md) to build your own instrumentation. If you do try out the instrumentation api, please let us know if you have any questions/feedback.
 -->
 
 ### Is it applicable for Node or Browser or both

README.md

@@ -135,15 +135,15 @@ Approvers ([@open-telemetry/js-approvers](https://github.com/orgs/open-telemetry
 - [Naseem K. Ullah](https://github.com/naseemkullah), Transit
 - [Olivier Albertini](https://github.com/OlivierAlbertini), Ville de Montréal
 
-*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).*
+*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver).*
 
 Maintainers ([@open-telemetry/js-maintainers](https://github.com/orgs/open-telemetry/teams/javascript-maintainers)):
 
 - [Bartlomiej Obecny](https://github.com/obecny), LightStep
 - [Daniel Dyla](https://github.com/dyladan), Dynatrace
 - [Valentin Marchaud](https://github.com/vmarchaud), Open Source Contributor
 
-*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).*
+*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).*
 
 ### Thanks to all the people who already contributed
 
@@ -182,18 +182,17 @@ OpenTelemetry is vendor-agnostic and can upload data to any backend with various
 
 See the [OpenTelemetry registry](https://opentelemetry.io/registry/?s=node.js) for a list of exporters available.
 
-### Plugins
+### Instrumentations & Plugins
 
-OpenTelemetry can collect tracing data automatically using plugins. Vendors/Users can also create and use their own. Currently, OpenTelemetry supports automatic tracing for:
+OpenTelemetry can collect tracing data automatically using instrumentations. Vendors/Users can also create and use their own. Currently, OpenTelemetry supports automatic tracing for:
 
-#### Node Plugins
+#### Node Instrumentations & Plugins
 
 ##### Core
 
-- [@opentelemetry/plugin-grpc][otel-plugin-grpc]
+- [@opentelemetry/instrumentation-grpc][otel-instrumentation-grpc] previous [@opentelemetry/plugin-grpc][otel-plugin-grpc]
 - [@opentelemetry/plugin-grpc-js][otel-plugin-grpc-js]
-- [@opentelemetry/plugin-http][otel-plugin-http]
-- [@opentelemetry/plugin-https][otel-plugin-https]
+- [@opentelemetry/instrumentation-http][otel-plugin-http] previous [@opentelemetry/plugin-http][otel-plugin-http] and [@opentelemetry/plugin-https][otel-plugin-https]
 
 ##### Contrib
 
@@ -215,7 +214,7 @@ These plugins are hosted at <https://github.com/open-telemetry/opentelemetry-js-
 ##### Core
 
 - [@opentelemetry/instrumentation-xml-http-request][otel-instrumentation-xml-http-request]
-- [@opentelemetry/plugin-fetch][otel-plugin-fetch]
+- [@opentelemetry/instrumentation-fetch][otel-instrumentation-fetch]
 
 ##### Contrib
 
@@ -224,7 +223,7 @@ These plugins are hosted at <https://github.com/open-telemetry/opentelemetry-js-
 - [@opentelemetry/plugin-document-load][otel-contrib-plugin-document-load]
 - [@opentelemetry/plugin-user-interaction][otel-contrib-plugin-user-interaction]
 
-To request automatic tracing support for a module not on this list, please [file an issue](https://github.com/open-telemetry/opentelemetry-js/issues). Alternatively, you can [write a plugin yourself](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/plugin-guide.md).
+To request automatic tracing support for a module not on this list, please [file an issue](https://github.com/open-telemetry/opentelemetry-js/issues). Alternatively, you can [write an instrumentation yourself](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/instrumentation-guide.md).
 
 ### Shims
 
@@ -234,6 +233,65 @@ To request automatic tracing support for a module not on this list, please [file
 
 ## Upgrade guidelines
 
+### 0.16.0 to 0.17.0
+
+[PR-1855](https://github.com/open-telemetry/opentelemetry-js/pull/1855) Use instrumentation loader to load plugins and instrumentations
+
+- Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use `registerInstrumentations` instead
+
+```javascript
+//Previously in node
+const provider = new NodeTracerProvider({
+ plugins: {
+ '@grpc/grpc-js': {
+ enabled: true,
+ path: '@opentelemetry/plugin-grpc-js',
+ },
+ }
+});
+
+// Now
+const provider = new NodeTracerProvider();
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+registerInstrumentations({
+ instrumentations: [
+ {
+ plugins: {
+ '@grpc/grpc-js': {
+ enabled: true,
+ path: '@opentelemetry/plugin-grpc-js',
+ },
+ }
+ }
+ ],
+ tracerProvider: provider,
+});
+
+// or if you want to load only default instrumentations / plugins
+registerInstrumentations({
+ tracerProvider: provider,
+});
+
+//Previously in browser
+const provider = new WebTracerProvider({
+ plugins: [
+ new DocumentLoad()
+ ]
+});
+// Now
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const provider = new WebTracerProvider();
+registerInstrumentations({
+ instrumentations: [
+ new DocumentLoad(),
+ ],
+});
+```
+
+- `registerInstrumentations` supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations
+
+## Upgrade guidelines
+
 ### 0.15.0 to 0.16.0
 
 [PR-1874](https://github.com/open-telemetry/opentelemetry-js/pull/1874) More specific API type names
@@ -290,11 +348,15 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [otel-metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-metrics
 [otel-node]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node
 
-[otel-plugin-fetch]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-plugin-fetch
 [otel-plugin-grpc]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-plugin-grpc
 [otel-plugin-grpc-js]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-plugin-grpc-js
 [otel-plugin-http]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-plugin-http
 [otel-plugin-https]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-plugin-https
+
+[otel-instrumentation-fetch]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-fetch
+[otel-instrumentation-grpc]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-grpc
+[otel-instrumentation-http]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-http
+[otel-instrumentation-https]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-https
 [otel-instrumentation-xml-http-request]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-xml-http-request
 
 [otel-shim-opentracing]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-shim-opentracing

doc/plugin-guide.md → doc/instrumentation-guide.md

@@ -1,6 +1,6 @@
-# Plugin Developer Guide
+# Instrumentation Developer Guide
 
-The `NodeTracerProvider` or `Node-SDK` is driven by a set of plugins that describe how to patch a module to generate trace spans when that module is used. We provide out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system (see [builtin plugins][builtin-plugins]), and provide a means for developers to create their own.
+We provide out-of-the-box instrumentations for many popular frameworks and libraries by using an instrumentation system (see [builtin instrumentations][builtin-instrumentations]), and provide a means for developers to create their own.
 
 We strongly recommended to create a dedicated package for newly added plugin, example: `@opentelemetry/plugin-xxx`.
 
@@ -45,7 +45,7 @@ We recommend using [`shimmer`][shimmer] to modify function properties on objects
 Please refer to the [HTTP instrumentation][http-plugin] or [gRPC instrumentation][grpc-plugin] for more comprehensive examples.
 
 [shimmer]: https://github.com/othiym23/shimmer
-[builtin-plugins]: https://github.com/open-telemetry/opentelemetry-js#plugins
+[builtin-instrumentations]: https://github.com/open-telemetry/opentelemetry-js#instrumentations&plugins
 [base-plugin]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-core/src/platform/node/BasePlugin.ts
 [http-plugin]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-plugin-http/src/http.ts#L44
 [grpc-plugin]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-plugin-grpc/src/grpc.ts#L52

examples/grpc-js/client.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const api = require('@opentelemetry/api');
-const tracer = require('./tracer')('example-grpc-client');
+const tracer = require('./tracer')('example-grpc-js-client');
 // eslint-disable-next-line import/order
 const grpc = require('@grpc/grpc-js');
 const messages = require('./helloworld_pb');

examples/grpc-js/package.json

@@ -32,6 +32,7 @@
  "@opentelemetry/api": "^0.16.0",
  "@opentelemetry/exporter-jaeger": "^0.16.0",
  "@opentelemetry/exporter-zipkin": "^0.16.0",
+ "@opentelemetry/instrumentation": "^0.16.0",
  "@opentelemetry/node": "^0.16.0",
  "@opentelemetry/plugin-grpc-js": "^0.16.0",
  "@opentelemetry/tracing": "^0.16.0",

examples/grpc-js/server.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const api = require('@opentelemetry/api');
-const tracer = require('./tracer')(('example-grpc-server'));
+const tracer = require('./tracer')(('example-grpc-js-server'));
 // eslint-disable-next-line import/order
 const grpc = require('@grpc/grpc-js');
 

examples/grpc-js/tracer.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/api');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 const { NodeTracerProvider } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
@@ -9,13 +10,26 @@ const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
 const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
- const provider = new NodeTracerProvider({
- plugins: {
- '@grpc/grpc-js': {
- enabled: true,
- path: '@opentelemetry/plugin-grpc-js',
+ const provider = new NodeTracerProvider();
+ registerInstrumentations({
+ instrumentations: [
+ {
+ plugins: {
+ '@grpc/grpc-js': {
+ enabled: true,
+ path: '@opentelemetry/plugin-grpc-js',
+ // // when boostraping with lerna for testing purposes
+ // path: `${__dirname}/../../packages/opentelemetry-plugin-grpc-js/build/src`
+ },
+ // // when boostraping with lerna for testing purposes
+ // 'http': {
+ // enabled: true,
+ // path: `${__dirname}/../../packages/opentelemetry-plugin-http/build/src`
+ // },
+ },
  },
- },
+ ],
+ tracerProvider: provider,
  });
 
  let exporter;

examples/grpc/package.json

@@ -31,6 +31,7 @@
  "@opentelemetry/api": "^0.16.0",
  "@opentelemetry/exporter-jaeger": "^0.16.0",
  "@opentelemetry/exporter-zipkin": "^0.16.0",
+ "@opentelemetry/instrumentation": "^0.16.0",
  "@opentelemetry/node": "^0.16.0",
  "@opentelemetry/plugin-grpc": "^0.16.0",
  "@opentelemetry/tracing": "^0.16.0",

examples/grpc/tracer.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/api');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 const { NodeTracerProvider } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
@@ -10,6 +11,20 @@ const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
  const provider = new NodeTracerProvider();
+ registerInstrumentations({
+ tracerProvider: provider,
+ // // when boostraping with lerna for testing purposes
+ // instrumentations: [
+ // {
+ // plugins: {
+ // grpc: {
+ // enabled: true,
+ // path: `${__dirname}/../../packages/opentelemetry-plugin-grpc/build/src`
+ // }
+ // }
+ // }
+ // ],
+ });
 
  let exporter;
  if (EXPORTER.toLowerCase().startsWith('z')) {

examples/http/package.json

@@ -31,6 +31,7 @@
  "@opentelemetry/api": "^0.16.0",
  "@opentelemetry/exporter-jaeger": "^0.16.0",
  "@opentelemetry/exporter-zipkin": "^0.16.0",
+ "@opentelemetry/instrumentation": "^0.16.0",
  "@opentelemetry/node": "^0.16.0",
  "@opentelemetry/plugin-http": "^0.16.0",
  "@opentelemetry/tracing": "^0.16.0"

examples/http/tracer.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/api');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 const { NodeTracerProvider } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
@@ -10,6 +11,20 @@ const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
  const provider = new NodeTracerProvider();
+ registerInstrumentations({
+ tracerProvider: provider,
+ // // when boostraping with lerna for testing purposes
+ // instrumentations: [
+ // {
+ // plugins: {
+ // http: {
+ // enabled: true,
+ // path: `${__dirname}/../../packages/opentelemetry-plugin-http/build/src`
+ // }
+ // }
+ // }
+ // ],
+ });
 
  let exporter;
  if (EXPORTER.toLowerCase().startsWith('z')) {

examples/https/package.json

@@ -32,6 +32,7 @@
  "@opentelemetry/api": "^0.16.0",
  "@opentelemetry/exporter-jaeger": "^0.16.0",
  "@opentelemetry/exporter-zipkin": "^0.16.0",
+ "@opentelemetry/instrumentation": "^0.16.0",
  "@opentelemetry/node": "^0.16.0",
  "@opentelemetry/plugin-https": "^0.16.0",
  "@opentelemetry/tracing": "^0.16.0"

examples/https/tracer.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/api');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 const { NodeTracerProvider } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
@@ -12,6 +13,20 @@ process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 module.exports = (serviceName) => {
  let exporter;
  const provider = new NodeTracerProvider();
+ registerInstrumentations({
+ tracerProvider: provider,
+ // when boostraping with lerna for testing purposes
+ // instrumentations: [
+ // {
+ // plugins: {
+ // https: {
+ // enabled: true,
+ // path: `${__dirname}/../../packages/opentelemetry-plugin-https/build/src`
+ // }
+ // }
+ // }
+ // ],
+ });
 
  if (EXPORTER.toLowerCase().startsWith('z')) {
  exporter = new ZipkinExporter({

examples/opentracing-shim/client.js

@@ -2,7 +2,7 @@
 
 const http = require('http');
 const opentracing = require('opentracing');
-const shim = require('./shim').shim('http_client_service');
+const shim = require('./shim').shim('http_client_opentracing');
 
 opentracing.initGlobalTracer(shim);
 const tracer = opentracing.globalTracer();

examples/opentracing-shim/package.json

@@ -31,6 +31,7 @@
  "dependencies": {
  "@opentelemetry/exporter-jaeger": "^0.16.0",
  "@opentelemetry/exporter-zipkin": "^0.16.0",
+ "@opentelemetry/instrumentation": "^0.16.0",
  "@opentelemetry/node": "^0.16.0",
  "@opentelemetry/shim-opentracing": "^0.16.0",
  "@opentelemetry/tracing": "^0.16.0",

examples/opentracing-shim/server.js

@@ -3,7 +3,7 @@
 const http = require('http');
 const opentracing = require('opentracing');
 const utils = require('./utils');
-const shim = require('./shim').shim('http_server_service');
+const shim = require('./shim').shim('http_server_opentracing');
 
 opentracing.initGlobalTracer(shim);
 const tracer = opentracing.globalTracer();