From 8be9ccbf5d4a8e0ca49d904e2fc5184b99f5f93c Mon Sep 17 00:00:00 2001 From: Vera Reynolds Date: Mon, 19 Jul 2021 19:10:48 -0600 Subject: [PATCH 1/3] docs: add quickstart code example --- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ce59d523d2..3bbccdcdcb 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,52 @@ The current version for each package can be found in the respective `package.jso ### Application Owner -To get started tracing your own application, see the [Getting Started Guide](getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/tracing][otel-tracing] +#### Install Dependencies + +```shell +npm install --save @opentelemetry/api +npm install --save @opentelemetry/node +npm install --save @opentelemetry/tracing +npm install --save @opentelemetry/auto-instrumentations-node +``` + +#### Instantiate Tracing + +```js +// tracing.js + +'use strict' + +const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node"); +const { registerInstrumentations } = require('@opentelemetry/instrumentation') +const { ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/tracing') +const { NodeTracerProvider } = require('@opentelemetry/node') +const { Resource } = require('@opentelemetry/resources'); +const { ResourceAttributes } = require('@opentelemetry/semantic-conventions'); + +const exporter = new ConsoleSpanExporter(); +const provider = new NodeTracerProvider({ + resource: new Resource({ + [ResourceAttributes.SERVICE_NAME]: 'my-service', + }), +}); +provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); +provider.register(); + +registerInstrumentations({ + instrumentations: [ + getNodeAutoInstrumentations(), + ], +}); +``` + +#### Run Your Application + +```shell +node -r ./tracing.js app.js +``` + +The above example will emit auto-instrumented telemetry about your application to the console. For a more in-depth example, see the [Getting Started Guide](getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/tracing][otel-tracing] ### Library Author From 39e8e378cda88ed9bf792c97b0c06690933d412d Mon Sep 17 00:00:00 2001 From: Vera Reynolds Date: Wed, 21 Jul 2021 12:55:23 -0600 Subject: [PATCH 2/3] docs: update quickstart code example * add comments * make a note about the meta package * use new SemanticResourceAttributes name --- README.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3bbccdcdcb..66381bdfd7 100644 --- a/README.md +++ b/README.md @@ -75,11 +75,12 @@ The current version for each package can be found in the respective `package.jso ```shell npm install --save @opentelemetry/api -npm install --save @opentelemetry/node -npm install --save @opentelemetry/tracing +npm install --save @opentelemetry/sdk-node npm install --save @opentelemetry/auto-instrumentations-node ``` +**Note:** `auto-instrumentations-node` is a meta package from [opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node) that provides a simple way to initialize multiple Node.js instrumentations. + #### Instantiate Tracing ```js @@ -87,22 +88,28 @@ npm install --save @opentelemetry/auto-instrumentations-node 'use strict' -const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node"); +const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node'); const { registerInstrumentations } = require('@opentelemetry/instrumentation') const { ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/tracing') const { NodeTracerProvider } = require('@opentelemetry/node') const { Resource } = require('@opentelemetry/resources'); -const { ResourceAttributes } = require('@opentelemetry/semantic-conventions'); +const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions'); +// configure a tracer provider that exports telemetry data to the console const exporter = new ConsoleSpanExporter(); const provider = new NodeTracerProvider({ resource: new Resource({ - [ResourceAttributes.SERVICE_NAME]: 'my-service', + [SemanticResourceAttributes.SERVICE_NAME]: 'my-service', }), }); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); + +// register the tracer provider with the OpenTelemetry API +// this enables the API to record telemetry provider.register(); +// enable auto-instrumentation +// this activates and connects each instrumentation to the registered tracer provider registerInstrumentations({ instrumentations: [ getNodeAutoInstrumentations(), @@ -116,7 +123,7 @@ registerInstrumentations({ node -r ./tracing.js app.js ``` -The above example will emit auto-instrumented telemetry about your application to the console. For a more in-depth example, see the [Getting Started Guide](getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/tracing][otel-tracing] +The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the [Getting Started Guide](getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/tracing][otel-tracing] ### Library Author From ac2380a7414e5ea7da08561ac5cce13da1afc1a8 Mon Sep 17 00:00:00 2001 From: Vera Reynolds Date: Fri, 23 Jul 2021 13:55:49 -0600 Subject: [PATCH 3/3] docs: update quickstart code sample * use sdk-node initializer --- README.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 66381bdfd7..0ccfa26922 100644 --- a/README.md +++ b/README.md @@ -88,32 +88,36 @@ npm install --save @opentelemetry/auto-instrumentations-node 'use strict' +const process = require('process'); +const opentelemetry = require('@opentelemetry/sdk-node'); const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node'); -const { registerInstrumentations } = require('@opentelemetry/instrumentation') -const { ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/tracing') -const { NodeTracerProvider } = require('@opentelemetry/node') +const { ConsoleSpanExporter } = require('@opentelemetry/tracing'); const { Resource } = require('@opentelemetry/resources'); const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions'); -// configure a tracer provider that exports telemetry data to the console -const exporter = new ConsoleSpanExporter(); -const provider = new NodeTracerProvider({ +// configure the SDK to export telemetry data to the console +// enable all auto-instrumentations from the meta package +const traceExporter = new ConsoleSpanExporter(); +const sdk = new opentelemetry.NodeSDK({ resource: new Resource({ [SemanticResourceAttributes.SERVICE_NAME]: 'my-service', }), + traceExporter, + instrumentations: [getNodeAutoInstrumentations()] }); -provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); -// register the tracer provider with the OpenTelemetry API +// initialize the SDK and register with the OpenTelemetry API // this enables the API to record telemetry -provider.register(); - -// enable auto-instrumentation -// this activates and connects each instrumentation to the registered tracer provider -registerInstrumentations({ - instrumentations: [ - getNodeAutoInstrumentations(), - ], +sdk.start() + .then(() => console.log('Tracing initialized')) + .catch((error) => console.log('Error initializing tracing', error)); + +// gracefully shut down the SDK on process exit +process.on('SIGTERM', () => { + sdk.shutdown() + .then(() => console.log('Tracing terminated')) + .catch((error) => console.log('Error terminating tracing', error)) + .finally(() => process.exit(0)); }); ```