From 02c1d66b765644e5a2eafd58ed7197505e0548e0 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Thu, 12 Mar 2020 16:50:22 -0400 Subject: [PATCH] chore: update examples to use register (#848) --- examples/basic-tracer-node/index.js | 12 +++- examples/basic-tracer-node/multi_exporter.js | 67 ------------------- examples/dns/tracer.js | 2 +- examples/express/tracer.js | 2 +- examples/grpc/tracer.js | 4 +- examples/grpc_dynamic_codegen/tracer.js | 4 +- examples/http/tracer.js | 4 +- examples/https/tracer.js | 4 +- examples/ioredis/tracer.js | 2 +- examples/mysql/tracer.js | 4 +- examples/postgres/tracer.js | 2 +- examples/redis/tracer.js | 4 +- examples/stackdriver-trace/index.js | 4 +- getting-started/README.md | 9 ++- getting-started/traced-example/tracing.js | 6 +- getting-started/ts-example/README.md | 8 +-- getting-started/ts-example/tracing.ts | 6 +- .../README.md | 6 +- packages/opentelemetry-node/README.md | 10 ++- packages/opentelemetry-tracing/README.md | 5 +- 20 files changed, 51 insertions(+), 114 deletions(-) delete mode 100644 examples/basic-tracer-node/multi_exporter.js diff --git a/examples/basic-tracer-node/index.js b/examples/basic-tracer-node/index.js index ab8ce39afc..5db3fd1ffc 100644 --- a/examples/basic-tracer-node/index.js +++ b/examples/basic-tracer-node/index.js @@ -11,8 +11,16 @@ const exporter = new JaegerExporter({ serviceName: 'basic-service' }); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); -// Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings -opentelemetry.trace.setGlobalTracerProvider(provider); +/** + * Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings. + * + * This registers the tracer provider with the OpenTelemetry API as the global + * tracer provider. This means when you call API methods like + * `opentelemetry.trace.getTracer`, they will use this tracer provider. If you + * do not register a global tracer provider, instrumentation which calls these + * methods will recieve no-op implementations. + */ +provider.register(); const tracer = opentelemetry.trace.getTracer('example-basic-tracer-node'); // Create a span. A span must be closed. diff --git a/examples/basic-tracer-node/multi_exporter.js b/examples/basic-tracer-node/multi_exporter.js deleted file mode 100644 index 35d344e5c4..0000000000 --- a/examples/basic-tracer-node/multi_exporter.js +++ /dev/null @@ -1,67 +0,0 @@ -'use strict'; - -const opentelemetry = require('@opentelemetry/api'); -const { BasicTracerProvider, BatchSpanProcessor, SimpleSpanProcessor } = require('@opentelemetry/tracing'); -const { JaegerExporter } = require('@opentelemetry/exporter-jaeger'); -const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin'); -const { CollectorExporter } = require('@opentelemetry/exporter-collector'); - -const provider = new BasicTracerProvider(); - -const zipkinExporter = new ZipkinExporter({ serviceName: 'basic-service' }); -const jaegerExporter = new JaegerExporter({ - serviceName: 'basic-service', -}); -const collectorExporter = new CollectorExporter({ serviceName: 'basic-service' }); - -// It is recommended to use this BatchSpanProcessor for better performance -// and optimization, especially in production. -provider.addSpanProcessor(new BatchSpanProcessor(zipkinExporter, { - // This is added for example, default size is 100. - bufferSize: 10, -})); - -const tracer = opentelemetry.trace.getTracer('default'); - -tracer.addSpanProcessor(new BatchSpanProcessor(jaegerExporter), { - bufferSize: 10, -}); - -provider.addSpanProcessor(new SimpleSpanProcessor(collectorExporter)); - -// Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings -opentelemetry.trace.setGlobalTracerProvider(provider); - -// Create a span. A span must be closed. -const parentSpan = tracer.startSpan('main'); -for (let i = 0; i < 10; i += 1) { - doWork(parentSpan); -} -// Be sure to end the span. -parentSpan.end(); - -// flush and close the connection. -zipkinExporter.shutdown(); -jaegerExporter.shutdown(); -collectorExporter.shutdown(); - -function doWork(parent) { - // Start another span. In this example, the main method already started a - // span, so that'll be the parent span, and this will be a child span. - const span = tracer.startSpan('doWork', { - parent, - }); - - // simulate some random work. - for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) { - // empty - } - - // Set attributes to the span. - span.setAttribute('key', 'value'); - - // Annotate our span to capture metadata about our operation - span.addEvent('invoking doWork'); - - span.end(); -} diff --git a/examples/dns/tracer.js b/examples/dns/tracer.js index aa05d208aa..ac0d70efef 100644 --- a/examples/dns/tracer.js +++ b/examples/dns/tracer.js @@ -34,7 +34,7 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + provider.register(); return opentelemetry.trace.getTracer('dns-example'); }; diff --git a/examples/express/tracer.js b/examples/express/tracer.js index 578c9a3e05..b5cdf1aab6 100644 --- a/examples/express/tracer.js +++ b/examples/express/tracer.js @@ -37,7 +37,7 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + provider.register(); return opentelemetry.trace.getTracer('express-example'); }; diff --git a/examples/grpc/tracer.js b/examples/grpc/tracer.js index 1e54ad4773..cee15c735f 100644 --- a/examples/grpc/tracer.js +++ b/examples/grpc/tracer.js @@ -31,8 +31,8 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('grpc-example'); }; diff --git a/examples/grpc_dynamic_codegen/tracer.js b/examples/grpc_dynamic_codegen/tracer.js index 7c292a8d18..f027899d1e 100644 --- a/examples/grpc_dynamic_codegen/tracer.js +++ b/examples/grpc_dynamic_codegen/tracer.js @@ -34,8 +34,8 @@ module.exports = (serviceName) => { // and optimization, especially in production. provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('grpc-dynamic-codegen-example'); }; diff --git a/examples/http/tracer.js b/examples/http/tracer.js index 5d3562cc13..9c48468b5c 100644 --- a/examples/http/tracer.js +++ b/examples/http/tracer.js @@ -24,8 +24,8 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('http-example'); }; diff --git a/examples/https/tracer.js b/examples/https/tracer.js index 3e0963e12d..80d0a9b8ac 100644 --- a/examples/https/tracer.js +++ b/examples/https/tracer.js @@ -25,8 +25,8 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('https-example'); }; diff --git a/examples/ioredis/tracer.js b/examples/ioredis/tracer.js index cbb6d71e3b..ffa1fdc054 100644 --- a/examples/ioredis/tracer.js +++ b/examples/ioredis/tracer.js @@ -12,6 +12,6 @@ const exporter = new JaegerExporter({ serviceName: 'ioredis-example' }); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); // Initialize the OpenTelemetry APIs to use the BasicTracer bindings -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); module.exports = opentelemetry.trace.getTracer('ioredis-example'); diff --git a/examples/mysql/tracer.js b/examples/mysql/tracer.js index ddcfeb8307..097cd0a8fb 100644 --- a/examples/mysql/tracer.js +++ b/examples/mysql/tracer.js @@ -27,8 +27,8 @@ module.exports = (serviceName) => { serviceName, }))); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('mysql-example'); }; diff --git a/examples/postgres/tracer.js b/examples/postgres/tracer.js index b570f16d44..6cc640df6a 100644 --- a/examples/postgres/tracer.js +++ b/examples/postgres/tracer.js @@ -46,7 +46,7 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); // Initialize the OpenTelemetry APIs to use the BasicTracer bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + provider.register(); return opentelemetry.trace.getTracer('example-postgres'); }; diff --git a/examples/redis/tracer.js b/examples/redis/tracer.js index 4c38d75590..5c707ca291 100644 --- a/examples/redis/tracer.js +++ b/examples/redis/tracer.js @@ -25,8 +25,8 @@ module.exports = (serviceName) => { provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); - // Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings - opentelemetry.trace.setGlobalTracerProvider(provider); + // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings + provider.register(); return opentelemetry.trace.getTracer('redis-example'); }; diff --git a/examples/stackdriver-trace/index.js b/examples/stackdriver-trace/index.js index c15de399e3..11f5d5a0db 100644 --- a/examples/stackdriver-trace/index.js +++ b/examples/stackdriver-trace/index.js @@ -15,8 +15,8 @@ const provider = new BasicTracerProvider(); // Configure span processor to send spans to the provided exporter provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); -// Initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings -opentelemetry.trace.setGlobalTracerProvider(provider); +// Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings +provider.register(); const tracer = opentelemetry.trace.getTracer('stackdriver-basic'); // Create a span. A span must be closed. diff --git a/getting-started/README.md b/getting-started/README.md index c6e8897746..23f2032d03 100644 --- a/getting-started/README.md +++ b/getting-started/README.md @@ -73,14 +73,14 @@ Create a file named `tracing.js` and add the following code: ```javascript 'use strict'; -const opentelemetry = require("@opentelemetry/api"); +const { LogLevel } = require("@opentelemetry/core"); const { NodeTracerProvider } = require("@opentelemetry/node"); const provider = new NodeTracerProvider({ - logLevel: opentelemetry.LogLevel.ERROR + logLevel: LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); ``` If you run your application now with `node -r ./tracing.js app.js`, your application will create and propagate traces over HTTP. If an already instrumented service that supports [Trace Context](https://www.w3.org/TR/trace-context/) headers calls your application using HTTP, and you call another application using HTTP, the Trace Context headers will be correctly propagated. @@ -109,7 +109,6 @@ After these dependencies are installed, we will need to initialize and register ```javascript 'use strict'; -const opentelemetry = require("@opentelemetry/api"); const { LogLevel } = require("@opentelemetry/core"); const { NodeTracerProvider } = require("@opentelemetry/node"); const { SimpleSpanProcessor } = require("@opentelemetry/tracing"); @@ -119,7 +118,7 @@ const provider = new NodeTracerProvider({ logLevel: LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); provider.addSpanProcessor( new SimpleSpanProcessor( diff --git a/getting-started/traced-example/tracing.js b/getting-started/traced-example/tracing.js index c5f18e3d56..fcb5b2e610 100644 --- a/getting-started/traced-example/tracing.js +++ b/getting-started/traced-example/tracing.js @@ -1,12 +1,11 @@ "use strict"; -const opentelemetry = require("@opentelemetry/api"); +const { LogLevel } = require("@opentelemetry/core"); const { NodeTracerProvider } = require("@opentelemetry/node"); const { SimpleSpanProcessor } = require("@opentelemetry/tracing"); const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin"); -const provider = new NodeTracerProvider({ logLevel: opentelemetry.LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +const provider = new NodeTracerProvider({ logLevel: LogLevel.ERROR }); provider.addSpanProcessor( new SimpleSpanProcessor( @@ -19,4 +18,5 @@ provider.addSpanProcessor( ) ); +provider.register(); console.log("tracing initialized"); diff --git a/getting-started/ts-example/README.md b/getting-started/ts-example/README.md index c7dcd8c12a..66b7d344e6 100644 --- a/getting-started/ts-example/README.md +++ b/getting-started/ts-example/README.md @@ -80,7 +80,7 @@ const provider: NodeTracerProvider = new NodeTracerProvider({ logLevel: LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); ``` If you run your application now with `ts-node -r ./tracing.ts app.ts`, your application will create and propagate traces over HTTP. If an already instrumented service that supports [Trace Context](https://www.w3.org/TR/trace-context/) headers calls your application using HTTP, and you call another application using HTTP, the Trace Context headers will be correctly propagated. @@ -107,7 +107,7 @@ $ # npm install @opentelemetry/exporter-jaeger After these dependencies are installed, we will need to initialize and register them. Modify `tracing.ts` so that it matches the following code snippet, replacing the service name `"getting-started"` with your own service name if you wish. ```typescript -import * as opentelemetry from '@opentelemetry/api'; +import { LogLevel } from '@opentelemetry/core'; import { NodeTracerProvider } from '@opentelemetry/node'; import { SimpleSpanProcessor } from '@opentelemetry/tracing'; @@ -116,10 +116,10 @@ import { ZipkinExporter } from '@opentelemetry/exporter-zipkin'; // import { JaegerExporter } from '@opentelemetry/exporter-jaeger'; const provider: NodeTracerProvider = new NodeTracerProvider({ - logLevel: opentelemetry.LogLevel.ERROR + logLevel: LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); provider.addSpanProcessor( new SimpleSpanProcessor( diff --git a/getting-started/ts-example/tracing.ts b/getting-started/ts-example/tracing.ts index 4e72e91e31..7afb8077a7 100644 --- a/getting-started/ts-example/tracing.ts +++ b/getting-started/ts-example/tracing.ts @@ -1,13 +1,13 @@ -import * as opentelemetry from "@opentelemetry/api"; +import { LogLevel } from '@opentelemetry/core'; import { NodeTracerProvider } from "@opentelemetry/node"; import { SimpleSpanProcessor } from "@opentelemetry/tracing"; import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"; const provider: NodeTracerProvider = new NodeTracerProvider({ - logLevel: opentelemetry.LogLevel.ERROR + logLevel: LogLevel.ERROR }); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); provider.addSpanProcessor( new SimpleSpanProcessor( diff --git a/packages/opentelemetry-exporter-collector/README.md b/packages/opentelemetry-exporter-collector/README.md index 9fb5987a48..275674470c 100644 --- a/packages/opentelemetry-exporter-collector/README.md +++ b/packages/opentelemetry-exporter-collector/README.md @@ -15,7 +15,6 @@ npm install --save @opentelemetry/exporter-collector ## Usage in Web ```js -import * as opentelemetry from '@opentelemetry/api'; import { SimpleSpanProcessor } from '@opentelemetry/tracing'; import { WebTracerProvider } from '@opentelemetry/web'; import { CollectorExporter } from '@opentelemetry/exporter-collector' @@ -28,13 +27,12 @@ const provider = new WebTracerProvider(); const exporter = new CollectorExporter(collectorOptions); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); ``` ## Usage in Node ```js -const opentelemetry = require('@opentelemetry/api'); const { BasicTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/tracing'); const { CollectorExporter } = require('@opentelemetry/exporter-collector'); @@ -46,7 +44,7 @@ const provider = new BasicTracerProvider(); const exporter = new CollectorExporter(collectorOptions); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register(); ``` diff --git a/packages/opentelemetry-node/README.md b/packages/opentelemetry-node/README.md index cc7ef3dae9..d228c4dfdb 100644 --- a/packages/opentelemetry-node/README.md +++ b/packages/opentelemetry-node/README.md @@ -52,8 +52,7 @@ npm install --save @opentelemetry/plugin-https The following code will configure the `NodeTracerProvider` to instrument `http` using `@opentelemetry/plugin-http`. ```js -const opentelemetry = require('@opentelemetry/api'); -const { NodeTracerProvider } = require('@opentelemetry/node'); +const { NodeTracerProvider } = require('@/node'); // Create and configure NodeTracerProvider const provider = new NodeTracerProvider({ @@ -61,14 +60,14 @@ const provider = new NodeTracerProvider({ http: { enabled: true, // You may use a package name or absolute path to the file. - path: '@opentelemetry/plugin-http', + path: '@/plugin-http', // http plugin options } } }); // Initialize the provider -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register() // Your application code - http will automatically be instrumented if // @opentelemetry/plugin-http is present @@ -78,14 +77,13 @@ const http = require('http'); To enable instrumentation for all [supported modules](https://github.com/open-telemetry/opentelemetry-js#plugins), create an instance of `NodeTracerProvider` without providing any plugin configuration to the constructor. ```js -const opentelemetry = require('@opentelemetry/api'); const { NodeTracerProvider } = require('@opentelemetry/node'); // Create and initialize NodeTracerProvider const provider = new NodeTracerProvider(); // Initialize the provider -opentelemetry.trace.setGlobalTracerProvider(provider); +provider.register() // Your application code // ... diff --git a/packages/opentelemetry-tracing/README.md b/packages/opentelemetry-tracing/README.md index c591a8454b..e80b42c732 100644 --- a/packages/opentelemetry-tracing/README.md +++ b/packages/opentelemetry-tracing/README.md @@ -28,8 +28,9 @@ const opentelemetry = require('@opentelemetry/api'); const { BasicTracerProvider } = require('@opentelemetry/tracing'); // To start a trace, you first need to initialize the Tracer provider. -// NOTE: the default OpenTelemetry tracer provider does not record any tracing information. -opentelemetry.trace.setGlobalTracerProvider(new BasicTracerProvider()); +// NOTE: The default OpenTelemetry tracer provider does not record any tracing information. +// Registering a working tracer provider allows the API methods to record traces. +new BasicTracerProvider().register(); // To create a span in a trace, we used the global singleton tracer to start a new span. const span = opentelemetry.trace.getTracer('default').startSpan('foo');