chore: prefer use of global TracerProvider/MeterProvider (#2127)

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>
Co-authored-by: Valentin Marchaud <contact@vmarchaud.fr>

examples/grpc-js/tracer.js

@@ -12,12 +12,6 @@ const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
   const provider = new NodeTracerProvider();
-  registerInstrumentations({
-    instrumentations: [
-      new GrpcInstrumentation(),
-    ],
-    tracerProvider: provider,
-  });
 
   let exporter;
   if (EXPORTER.toLowerCase().startsWith('z')) {
@@ -35,5 +29,11 @@ module.exports = (serviceName) => {
   // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
   provider.register();
 
+  registerInstrumentations({
+    instrumentations: [
+      new GrpcInstrumentation(),
+    ],
+  });
+
   return opentelemetry.trace.getTracer('grpc-js-example');
 };

examples/grpc/tracer.js

@@ -12,12 +12,6 @@ const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
   const provider = new NodeTracerProvider();
-  registerInstrumentations({
-    tracerProvider: provider,
-    instrumentations: [
-      new GrpcInstrumentation(),
-    ],
-  });
 
   let exporter;
   if (EXPORTER.toLowerCase().startsWith('z')) {
@@ -35,5 +29,11 @@ module.exports = (serviceName) => {
   // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
   provider.register();
 
+  registerInstrumentations({
+    instrumentations: [
+      new GrpcInstrumentation(),
+    ],
+  });
+
   return opentelemetry.trace.getTracer('grpc-example');
 };

examples/http/tracer.js

@@ -12,13 +12,6 @@ const EXPORTER = process.env.EXPORTER || '';
 
 module.exports = (serviceName) => {
   const provider = new NodeTracerProvider();
-  registerInstrumentations({
-    tracerProvider: provider,
-    // // when boostraping with lerna for testing purposes
-    instrumentations: [
-      new HttpInstrumentation(),
-    ],
-  });
 
   let exporter;
   if (EXPORTER.toLowerCase().startsWith('z')) {
@@ -36,5 +29,12 @@ module.exports = (serviceName) => {
   // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
   provider.register();
 
+  registerInstrumentations({
+    // // when boostraping with lerna for testing purposes
+    instrumentations: [
+      new HttpInstrumentation(),
+    ],
+  });
+
   return opentelemetry.trace.getTracer('http-example');
 };

examples/https/tracer.js

@@ -14,12 +14,6 @@ process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 module.exports = (serviceName) => {
   let exporter;
   const provider = new NodeTracerProvider();
-  registerInstrumentations({
-    tracerProvider: provider,
-    instrumentations: [
-      new HttpInstrumentation(),
-    ],
-  });
 
   if (EXPORTER.toLowerCase().startsWith('z')) {
     exporter = new ZipkinExporter({
@@ -36,5 +30,11 @@ module.exports = (serviceName) => {
   // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
   provider.register();
 
+  registerInstrumentations({
+    instrumentations: [
+      new HttpInstrumentation(),
+    ],
+  });
+
   return opentelemetry.trace.getTracer('https-example');
 };

examples/opentracing-shim/shim.js

@@ -9,14 +9,14 @@ const { TracerShim } = require('@opentelemetry/shim-opentracing');
 
 function shim(serviceName) {
   const provider = new NodeTracerProvider();
-  registerInstrumentations({
-    tracerProvider: provider,
-  });
 
   provider.addSpanProcessor(new SimpleSpanProcessor(getExporter(serviceName)));
   // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
   provider.register();
 
+  registerInstrumentations({
+  });
+
   return new TracerShim(provider.getTracer('opentracing-shim'));
 }
 

examples/tracer-web/examples/fetch/index.js

@@ -11,6 +11,12 @@ import { B3Propagator } from '@opentelemetry/propagator-b3';
 import { registerInstrumentations } from '@opentelemetry/instrumentation';
 
 const provider = new WebTracerProvider();
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+provider.addSpanProcessor(new SimpleSpanProcessor(new CollectorTraceExporter()));
+provider.register({
+  contextManager: new ZoneContextManager(),
+  propagator: new B3Propagator(),
+});
 
 registerInstrumentations({
   instrumentations: [
@@ -20,17 +26,9 @@ registerInstrumentations({
         'https://cors-test.appspot.com/test',
         'https://httpbin.org/get',
       ],
-      clearTimingResources: true
+      clearTimingResources: true,
     }),
   ],
-  tracerProvider: provider,
-});
-
-provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
-provider.addSpanProcessor(new SimpleSpanProcessor(new CollectorTraceExporter()));
-provider.register({
-  contextManager: new ZoneContextManager(),
-  propagator: new B3Propagator(),
 });
 
 const webTracerWithZone = provider.getTracer('example-tracer-web');

examples/tracer-web/examples/xml-http-request/index.js

@@ -8,6 +8,13 @@ import { B3Propagator } from '@opentelemetry/propagator-b3';
 import { registerInstrumentations } from '@opentelemetry/instrumentation';
 
 const providerWithZone = new WebTracerProvider();
+providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new CollectorTraceExporter()));
+
+providerWithZone.register({
+  contextManager: new ZoneContextManager(),
+  propagator: new B3Propagator(),
+});
 
 registerInstrumentations({
   instrumentations: [
@@ -18,15 +25,6 @@ registerInstrumentations({
       ],
     }),
   ],
-  tracerProvider: providerWithZone,
-});
-
-providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
-providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new CollectorTraceExporter()));
-
-providerWithZone.register({
-  contextManager: new ZoneContextManager(),
-  propagator: new B3Propagator(),
 });
 
 const webTracerWithZone = providerWithZone.getTracer('example-tracer-web');

getting-started/README.md

@@ -4,8 +4,8 @@ This guide walks you through the setup and configuration process for a tracing b
 
 - [Getting started with OpenTelemetry JS](#getting-started-with-opentelemetry-js)
   - [Trace your application with OpenTelemetry](#trace-your-application-with-opentelemetry)
-    - [Set up a Tracing Backend](#set-up-a-tracing-backend)
-    - [Trace Your NodeJS Application](#trace-your-nodejs-application)
+    - [Set up a tracing backend](#set-up-a-tracing-backend)
+    - [Trace your NodeJS application](#trace-your-nodejs-application)
       - [Install the required OpenTelemetry libraries](#install-the-required-opentelemetry-libraries)
       - [Initialize a global tracer](#initialize-a-global-tracer)
       - [Initialize and register a trace exporter](#initialize-and-register-a-trace-exporter)
@@ -92,7 +92,6 @@ registerInstrumentations({
     new HttpInstrumentation(),
     new GrpcInstrumentation(),
   ],
-  tracerProvider: provider,
 });
 
 ```
@@ -153,7 +152,6 @@ registerInstrumentations({
     new HttpInstrumentation(),
     new GrpcInstrumentation(),
   ],
-  tracerProvider: provider,
 });
 
 console.log("tracing initialized");

getting-started/traced-example/tracing.js

@@ -24,7 +24,6 @@ provider.register();
 
 // load old default plugins
 registerInstrumentations({
-  tracerProvider: provider,
   instrumentations: [
     new ExpressInstrumentation(),
     new HttpInstrumentation(),

getting-started/ts-example/README.md

@@ -88,7 +88,6 @@ const provider: NodeTracerProvider = new NodeTracerProvider({
 provider.register();
 
 registerInstrumentations({
-  tracerProvider: provider,
   instrumentations: [
     new ExpressInstrumentation(),
     new HttpInstrumentation(),
@@ -137,8 +136,6 @@ const provider: NodeTracerProvider = new NodeTracerProvider({
   logLevel: LogLevel.ERROR,
 });
 
-provider.register();
-
 provider.addSpanProcessor(
   new SimpleSpanProcessor(
     new ZipkinExporter({
@@ -152,8 +149,9 @@ provider.addSpanProcessor(
   ),
 );
 
+provider.register();
+
 registerInstrumentations({
-  tracerProvider: provider,
   instrumentations: [
     new ExpressInstrumentation(),
     new HttpInstrumentation(),

getting-started/ts-example/traced-example/tracing.ts

@@ -10,9 +10,6 @@ const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-expre
 const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
 
 const provider: NodeTracerProvider = new NodeTracerProvider();
-
-provider.register();
-
 provider.addSpanProcessor(
   new SimpleSpanProcessor(
     new ZipkinExporter({
@@ -25,9 +22,9 @@ provider.addSpanProcessor(
     }),
   ),
 );
+provider.register();
 
 registerInstrumentations({
-  tracerProvider: provider,
   instrumentations: [
     new ExpressInstrumentation(),
     new HttpInstrumentation(),

packages/opentelemetry-instrumentation-fetch/README.md

@@ -33,7 +33,6 @@ provider.register({
 
 registerInstrumentations({
   instrumentations: [new FetchInstrumentation()],
-  tracerProvider: provider,
 });
 
 // or plugin can be also initialised separately and then set the tracer provider or meter provider

packages/opentelemetry-instrumentation-grpc/README.md

@@ -34,7 +34,6 @@ provider.register();
 
 registerInstrumentations({
   instrumentations: [new GrpcInstrumentation()]
-  tracerProvider: provider,
 });
 
 ```

packages/opentelemetry-instrumentation-http/README.md

@@ -35,7 +35,6 @@ provider.register();
 
 registerInstrumentations({
   instrumentations: [new HttpInstrumentation()],
-  tracerProvider: provider,
 });
 
 ```

packages/opentelemetry-instrumentation-xml-http-request/README.md

@@ -35,7 +35,6 @@ registerInstrumentations({
       propagateTraceHeaderCorsUrls: ['http://localhost:8090']
     }),
   ],
-  tracerProvider: provider,
 });
 
 

packages/opentelemetry-instrumentation/README.md

@@ -109,7 +109,7 @@ export class MyPlugin extends InstrumentationBase {
 // Later
 
 const myPLugin = new MyPlugin();
-myPLugin.setTracerProvider(provider); // this is optional
+myPLugin.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
 myPLugin.setMeterProvider(meterProvider); // this is optional
 myPLugin.enable();
 // or use Auto Loader
@@ -151,8 +151,8 @@ export class MyPlugin extends InstrumentationBase {
 // Later
 
 const myPLugin = new MyPlugin();
-myPLugin.setTracerProvider(provider);
-myPLugin.setMeterProvider(meterProvider);
+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();
 // or use Auto Loader
 ```
@@ -221,7 +221,8 @@ registerInstrumentations({
   instrumentations: [
     new HttpInstrumentation(),
   ],
-  tracerProvider: tracerProvider,
+  //tracerProvider: tracerProvider, // optional, only if global TracerProvider shouldn't be used
+  //meterProvider: meterProvider, // optional, only if global MeterProvider shouldn't be used
 });
 
 ```
@@ -249,10 +250,19 @@ registerInstrumentations({
       ],
     }),
   ],
-  tracerProvider: tracerProvider,
+  //tracerProvider: tracerProvider, // optional, only if global TracerProvider shouldn't be used
+  //meterProvider: meterProvider, // optional, only if global MeterProvider shouldn't be used
 });
 ```
 
+## Selection of the used TracerProvider/MeterProvider
+
+The `registerInstrumentations()` API allows to specify which `TracerProvider` and/or `MeterProvider` to use by the given options object.
+If nothing is specified the global registered provider is used. Usually this is what most users want therefore it's recommended to keep this default.
+
+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.
+
 ## License
 
 Apache 2.0 - See [LICENSE][license-url] for more information.

packages/opentelemetry-node/README.md

@@ -64,7 +64,6 @@ provider.register();
 // register and load instrumentation and old plugins - old plugins will be loaded automatically as previously
 // but instrumentations needs to be added
 registerInstrumentations({
-  tracerProvider: provider,
 });
 
 // Your application code - http will automatically be instrumented if
@@ -80,15 +79,16 @@ In the following example:
 - the http instrumentation has a custom config for a `requestHook`
 
 ```javascript
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
 const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
 
 const provider = new NodeTracerProvider();
+provider.register();
 
 // register and load instrumentation and old plugins - old plugins will be loaded automatically as previously
 // but instrumentations needs to be added
 registerInstrumentations({
-  tracerProvider: provider,
   instrumentations: [
     new ExpressInstrumentation(),
     new HttpInstrumentation({

packages/opentelemetry-sdk-node/src/sdk.ts

@@ -176,8 +176,6 @@ export class NodeSDK {
 
     registerInstrumentations({
       instrumentations: this._instrumentations,
-      tracerProvider: this._tracerProvider,
-      meterProvider: this._meterProvider,
     });
   }
 

packages/opentelemetry-web/README.md

@@ -52,7 +52,6 @@ registerInstrumentations({
   instrumentations: [
     new DocumentLoad(),
   ],
-  tracerProvider: provider,
 });
 
 ```