Use instrumentation loader to load plugins and instrumentations (#1855)

* chore: removing plugin loader from node, updating usage and docs * chore: testing and updating examples * chore: lint * chore: adding comment about usage * chore: adding upgrading guidelines
open-telemetry · Feb 5, 2021 · 9cfa92c · 9cfa92c
1 parent 9981763
commit 9cfa92c
Show file tree

Hide file tree

Showing 74 changed files with 380 additions and 1,249 deletions.
diff --git a/.github/ISSUE_TEMPLATE/request_for_instrumentation.md b/.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

diff --git a/README.md b/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

diff --git a/doc/plugin-guide.md → doc/instrumentation-guide.md b/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

diff --git a/examples/grpc-js/client.js b/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');

diff --git a/examples/grpc-js/package.json b/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",

diff --git a/examples/grpc-js/server.js b/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');
 

diff --git a/examples/grpc-js/tracer.js b/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;

diff --git a/examples/grpc/package.json b/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",

diff --git a/examples/grpc/tracer.js b/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')) {

diff --git a/examples/http/package.json b/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"

diff --git a/examples/http/tracer.js b/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')) {

diff --git a/examples/https/package.json b/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"

diff --git a/examples/https/tracer.js b/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({

diff --git a/examples/opentracing-shim/client.js b/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();

diff --git a/examples/opentracing-shim/package.json b/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",

diff --git a/examples/opentracing-shim/server.js b/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();