From 8f5e50c91cab6ad59a500ace23a1301d06fd7a57 Mon Sep 17 00:00:00 2001 From: Siim Kallas Date: Fri, 28 Oct 2022 11:44:28 +0300 Subject: [PATCH] chore: update repo docs for v2 (#585) * chore: update README * doc: clarify readme * doc: move sections around * doc: rip out signalfx example doc * chore: add collector endpoint to lycheeignore * doc: cleanup * doc: cleanup --- .lycheeignore | 1 + README.md | 131 +++++++++++-------------- docs/correlate-logs-traces.md | 12 +-- docs/http-instrumentation.md | 3 +- examples/express/.env.opentracing | 4 - examples/express/README.md | 17 +--- examples/express/package.json | 7 +- examples/express/tracer.opentracing.js | 8 -- examples/express/utils.js | 21 +--- 9 files changed, 67 insertions(+), 137 deletions(-) delete mode 100644 examples/express/.env.opentracing delete mode 100644 examples/express/tracer.opentracing.js diff --git a/.lycheeignore b/.lycheeignore index c3536ca3..039f0022 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -1,4 +1,5 @@ https://ingest/ https://docs.github.com/ http://localhost:4318/ +http://localhost:4317/ http://collector:4317/ diff --git a/README.md b/README.md index c48a690b..fd43f7c0 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,16 @@ # Splunk Distribution of OpenTelemetry for Node.js -> ## **Documentation for the current stable version (1.x) can be viewed [here](https://quickdraw.splunk.com/redirect/?product=Observability&location=nodejs.application&version=current).** -> ## **To access version 1.x examples and developer documentation, see [/tree/1.x](https://github.com/signalfx/splunk-otel-js/tree/1.x).** +> ## **Examples and developer documentation for version 1.x can be seen at [/tree/1.x](https://github.com/signalfx/splunk-otel-js/tree/1.x).** -The Splunk Distribution of [OpenTelemetry JS](https://github.com/open-telemetry/opentelemetry-js) automatically instruments your Node application to capture and report distributed traces to Splunk APM. +The Splunk Distribution of [OpenTelemetry JS](https://github.com/open-telemetry/opentelemetry-js) integrates with Splunk APM and automatically instruments your Node application to capture traces, collect runtime metrics, CPU and memory profiles. This Splunk distribution comes with the following defaults: - [W3C tracecontext and baggage propagation](https://www.w3.org/TR/trace-context). - [OTLP exporter](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-grpc) configured to send spans to a locally running [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) over gRPC - (default endpoint: `localhost:4317`). + (default endpoint: `http://localhost:4317`). - Unlimited default limits for [configuration options](#trace-configuration) to support full-fidelity traces. @@ -43,7 +42,7 @@ npm install @splunk/otel --save You can find a list of instrumentation packages supported out of the box [here](#default-instrumentation-packages). To install additional instrumentations or provide your own, see [instrumentations](./docs/instrumentations.md). -1. Run node app with the `-r @splunk/otel/instrument` CLI argument +2. Run node app with the `-r @splunk/otel/instrument` CLI argument ``` export OTEL_SERVICE_NAME=my-node-svc @@ -52,12 +51,6 @@ node -r @splunk/otel/instrument app.js That's it - the telemetry data is now sent to the locally running Opentelemetry Collector. You can also instrument your app programmatically as described [here](#instrument-with-code). -> Note: If you are using npm 6 or older, it'll warn you about missing peer -> dependencies. All of these dependencies are instrumentation packages and are -> completely optional. You can install the ones you need and ignore the rest. -> npm 7+ supports optional peer dependencies feature and will not complain -> about this. - ### Send data directly to Splunk Observability Cloud In order to send traces directly to Splunk Observability Cloud, you need to: @@ -65,27 +58,6 @@ In order to send traces directly to Splunk Observability Cloud, you need to: 1. Set `SPLUNK_REALM` to your Splunk APM realm (for example, `us0`). 1. Set the `SPLUNK_ACCESS_TOKEN` to your Splunk Observability Cloud [access token](https://docs.splunk.com/Observability/admin/authentication-tokens/api-access-tokens.html). -## Automatically instrument an application - -You can use the `-r` CLI flag to preload the instrumentation module and automatically instrument your Node.js application. -For example, if you normally started your application as follows: - -```bash -node index.js -``` - -Then you can automatically instrument your application by running - -```bash -node -r @splunk/otel/instrument index.js -``` - -## Correlate traces and logs - -The Splunk Distribution of OpenTelemetry JS automatically injects trace metadata into logs so that Node.js logging libraries can access it. You can use trace metadata to correlate traces with log events and explore logs in Observability Cloud. - -For more information, see [Correlating traces with logs](./docs/correlate-logs-traces.md). - ## Manually instrument an application You can also manually instrument your application by adding the following lines before everything else in your application. @@ -93,60 +65,75 @@ You can also manually instrument your application by adding the following lines ```js const { start } = require('@splunk/otel'); -start(); +start({ + serviceName: 'my-node-service', + endpoint: 'http://localhost:4317' +}); // rest of your application entry point script ``` -`start()` accept an optional `Options` argument. It can be used to customize many aspects of the observability pipeline. For example: + +`start()` accepts an optional `Options` argument. It can be used to customize many aspects of the observability pipeline. For example enabling runtime metrics and memory profiling: ```js start({ serviceName: 'my-node-service', + metrics: { runtimeMetricsEnabled: true }, + profiling: { memoryProfilingEnabled: true } }); ``` +For all of the possible options see [Advanced Configuration](./docs/advanced-config.md#advanced-configuration). + > `start` is destructive to Open Telemetry API globals. Any globals set before running `start` are overwritten. +## Correlate traces and logs + +The Splunk Distribution of OpenTelemetry JS automatically injects trace metadata into logs so that Node.js logging libraries can access it. You can use trace metadata to correlate traces with log events and explore logs in Observability Cloud. + +For more information, see [Correlating traces with logs](./docs/correlate-logs-traces.md). + ## Default Instrumentation Packages -By default the following instrumentations will automatically be enabled if installed. In order to use -any of these instrumentations, you'll need to install them with npm and then run your app with `-r @splunk/otel/instrument` flag as described above. - -* `@opentelemetry/instrumentation-amqplib` -* `@opentelemetry/instrumentation-aws-lambda` -* `@opentelemetry/instrumentation-aws-sdk` -* `@opentelemetry/instrumentation-bunyan` -* `@opentelemetry/instrumentation-cassandra-driver` -* `@opentelemetry/instrumentation-connect` -* `@opentelemetry/instrumentation-dns` -* `@opentelemetry/instrumentation-express` -* `@opentelemetry/instrumentation-fastify` -* `@opentelemetry/instrumentation-fs` -* `@opentelemetry/instrumentation-generic-pool` -* `@opentelemetry/instrumentation-graphql` -* `@opentelemetry/instrumentation-grpc` -* `@opentelemetry/instrumentation-hapi` -* `@opentelemetry/instrumentation-http` -* `@opentelemetry/instrumentation-ioredis` -* `@opentelemetry/instrumentation-knex` -* `@opentelemetry/instrumentation-koa` -* `@opentelemetry/instrumentation-memcached` -* `@opentelemetry/instrumentation-mongodb` -* `@opentelemetry/instrumentation-mysql` -* `@opentelemetry/instrumentation-mysql2` -* `@opentelemetry/instrumentation-nestjs-core` -* `@opentelemetry/instrumentation-net` -* `@opentelemetry/instrumentation-pg` -* `@opentelemetry/instrumentation-pino` -* `@opentelemetry/instrumentation-redis` -* `@opentelemetry/instrumentation-restify` -* `@opentelemetry/instrumentation-tedious` -* `@opentelemetry/instrumentation-winston` -* `opentelemetry-instrumentation-elasticsearch` -* `opentelemetry-instrumentation-kafkajs` -* `opentelemetry-instrumentation-mongoose` -* `opentelemetry-instrumentation-sequelize` -* `opentelemetry-instrumentation-typeorm` +By default the following instrumentations will automatically be enabled: + +* [`@opentelemetry/instrumentation-amqplib`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-amqplib) +* [`@opentelemetry/instrumentation-aws-lambda`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-lambda) +* [`@opentelemetry/instrumentation-aws-sdk`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk) +* [`@opentelemetry/instrumentation-bunyan`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan) +* [`@opentelemetry/instrumentation-cassandra-driver`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-cassandra) +* [`@opentelemetry/instrumentation-connect`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-connect) +* [`@opentelemetry/instrumentation-dataloader`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-dataloader) +* [`@opentelemetry/instrumentation-dns`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-dns) +* [`@opentelemetry/instrumentation-express`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express) +* [`@opentelemetry/instrumentation-fastify`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify) +* [`@opentelemetry/instrumentation-generic-pool`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool) +* [`@opentelemetry/instrumentation-graphql`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-graphql) +* [`@opentelemetry/instrumentation-grpc`](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc) +* [`@opentelemetry/instrumentation-hapi`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi) +* [`@opentelemetry/instrumentation-http`](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) +* [`@opentelemetry/instrumentation-ioredis`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis) +* [`@opentelemetry/instrumentation-knex`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex) +* [`@opentelemetry/instrumentation-koa`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-koa) +* [`@opentelemetry/instrumentation-memcached`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-memcached) +* [`@opentelemetry/instrumentation-mongodb`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb) +* [`@opentelemetry/instrumentation-mysql`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mysql) +* [`@opentelemetry/instrumentation-mysql2`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mysql2) +* [`@opentelemetry/instrumentation-nestjs-core`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core) +* [`@opentelemetry/instrumentation-net`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net) +* [`@opentelemetry/instrumentation-pg`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg) +* [`@opentelemetry/instrumentation-pino`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino) +* [`@opentelemetry/instrumentation-redis`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis) +* [`@opentelemetry/instrumentation-redis-4`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4) +* [`@opentelemetry/instrumentation-restify`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify) +* [`@opentelemetry/instrumentation-router`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-router) +* [`@opentelemetry/instrumentation-tedious`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-tedious) +* [`@opentelemetry/instrumentation-winston`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston) +* [`opentelemetry-instrumentation-elasticsearch`](https://github.com/aspecto-io/opentelemetry-ext-js/tree/master/packages/instrumentation-elasticsearch) +* [`opentelemetry-instrumentation-kafkajs`](https://github.com/aspecto-io/opentelemetry-ext-js/tree/master/packages/instrumentation-kafkajs) +* [`opentelemetry-instrumentation-mongoose`](https://github.com/aspecto-io/opentelemetry-ext-js/tree/master/packages/instrumentation-mongoose) +* [`opentelemetry-instrumentation-sequelize`](https://github.com/aspecto-io/opentelemetry-ext-js/tree/master/packages/instrumentation-sequelize) +* [`opentelemetry-instrumentation-typeorm`](https://github.com/aspecto-io/opentelemetry-ext-js/tree/master/packages/instrumentation-typeorm) You can find more instrumentation packages over at the [OpenTelemetry Registry](https://opentelemetry.io/registry/?language=js) and enable them manually as described above. diff --git a/docs/correlate-logs-traces.md b/docs/correlate-logs-traces.md index 636f66c2..7f3977e5 100644 --- a/docs/correlate-logs-traces.md +++ b/docs/correlate-logs-traces.md @@ -6,7 +6,7 @@ The Splunk Distribution of OpenTelemetry JS automatically injects trace metadata ## Supported logging libraries -The following logging librares are supported: +The Splunk Distribution of OpenTelemetry JS automatically supports the following libraries: - Bunyan - Pino @@ -25,14 +25,4 @@ The format of each log message depends on the logging library. The following is {"level":30,"time":1979374615686,"pid":728570,"hostname":"my_host","trace_id":"f8e261432221096329baf5e62090d856","span_id":"3235afe76b55fe51","trace_flags":"01","url":"/lkasd","msg":"request handler"} ``` -## Enable logs injection - -To enable log injection, install the instrumentation package for your logging library: - -``` -@opentelemetry/instrumentation-bunyan -@opentelemetry/instrumentation-pino -@opentelemetry/instrumentation-winston -``` - To inject trace data into formatted logs, refer to the documentation of each library. diff --git a/docs/http-instrumentation.md b/docs/http-instrumentation.md index d113fa8e..90287e9f 100644 --- a/docs/http-instrumentation.md +++ b/docs/http-instrumentation.md @@ -4,12 +4,11 @@ To capture HTTP header names as span attributes, you must specify a list of head ```js const { start } = require('@splunk/otel'); -const { getInstrumentations } = require('@splunk/otel/lib/instrumentations'); +const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http'); start({ tracing: { instrumentations: [ - ...getInstrumentations(), new HttpInstrumentation({ headersToSpanAttributes: { // Server side capturing, e.g. express diff --git a/examples/express/.env.opentracing b/examples/express/.env.opentracing deleted file mode 100644 index 2f418ee1..00000000 --- a/examples/express/.env.opentracing +++ /dev/null @@ -1,4 +0,0 @@ -SIGNALFX_ACCESS_TOKEN='0123456789abcdefghijkl' -SIGNALFX_SERVICE_NAME='collectorless-express-example' -SIGNALFX_ENDPOINT_URL='https://ingest.us0.signalfx.com/v2/trace' -SIGNALFX_SPAN_TAGS='deployment.environment:dev' diff --git a/examples/express/README.md b/examples/express/README.md index 4ec6cbb5..bfd69da3 100644 --- a/examples/express/README.md +++ b/examples/express/README.md @@ -24,11 +24,10 @@ This example app can be run in following ways: 1. Uninstrumented 2. Instrumented via OTel SDK, exporting to locally running collector 3. Instrumented via OTel SDK, exporting directly to Splunk APM -4. Instrumented via legacy OpenTracing SDK ### Uninstrumented -Original app files do not cointain any reference to neither OTel or OpenTracing, nor does it need the SDKs to be installed. To run the app as is, without tracing run the server and the client in different terminals: +Original app files do not contain any references to OpenTelemetry, nor does it need the SDKs to be installed. To run the app as is, without tracing run the server and the client in different terminals: ```shell node server.js @@ -65,20 +64,6 @@ npm run server:apm npm run client:apm ``` -If are not sure about the values to use for `.env`, but you're familiar with configuring the OpenTracing SDK, you can also use [.env.opentracing](./.env.opentracing) as the baseline configuration: The OTel configuration is automatically derived from the OpenTracing settings **in this example** (see [utils.js](./utils.js) for the conversions). - -### Instrumented via legacy OpenTracing SDK - -For comparison this example also includes the legacy OpenTracing SDK setup which can be run using predefined commands: - -```shell -npm run server:opentracing -# In a separate terminal: -npm run client:opentracing -``` - -These commands require a configuration in the `.env` file compatible with the [SignalFX Tracing Library](https://github.com/signalfx/signalfx-nodejs-tracing). See the [example](./.env.opentracing). - # License and versioning The Splunk distribution of OpenTelemetry JS Instrumentation is a diff --git a/examples/express/package.json b/examples/express/package.json index 1b2595d9..c265e50a 100644 --- a/examples/express/package.json +++ b/examples/express/package.json @@ -6,19 +6,16 @@ "client": "env-cmd --silent nodemon -r ./tracer.js client.js", "client:apm": "env-cmd -f .env.otlp-splunk nodemon -r ./tracer.js client.js", "client:collector": "env-cmd -f .env.collector nodemon -r ./tracer.js client.js", - "client:opentracing": "env-cmd --silent nodemon -r ./tracer.opentracing.js client.js", "start": "npm run server", "server": "env-cmd --silent nodemon -r ./tracer.js server.js", "server:apm": "env-cmd -f .env.otlp-splunk nodemon -r ./tracer.js server.js", - "server:collector": "env-cmd -f .env.collector nodemon -r ./tracer.js server.js", - "server:opentracing": "env-cmd --silent nodemon -r ./tracer.opentracing.js server.js" + "server:collector": "env-cmd -f .env.collector nodemon -r ./tracer.js server.js" }, "dependencies": { "@splunk/otel": "1.4.0", "axios": "^0.21.1", "env-cmd": "^10.1.0", - "express": "^4.17.1", - "signalfx-tracing": "^0.13.0" + "express": "^4.17.1" }, "devDependencies": { "nodemon": "^2.0.12" diff --git a/examples/express/tracer.opentracing.js b/examples/express/tracer.opentracing.js deleted file mode 100644 index 0048276f..00000000 --- a/examples/express/tracer.opentracing.js +++ /dev/null @@ -1,8 +0,0 @@ -console.log('Enabling tracing via OpenTracing'); -const { - logConfig, -} = require('./utils.js'); - -logConfig(); - -const tracer = require('signalfx-tracing').init() diff --git a/examples/express/utils.js b/examples/express/utils.js index 8f28988b..83158125 100644 --- a/examples/express/utils.js +++ b/examples/express/utils.js @@ -1,6 +1,6 @@ const isConfigVarEntry = ([key, value]) => { const lowercased = key.toLowerCase(); - return lowercased.includes('splunk') || lowercased.includes('signal') || lowercased.includes('otel'); + return lowercased.includes('splunk') || lowercased.includes('otel'); }; const redactSecretEntry = ([key, value]) => { @@ -20,28 +20,11 @@ const parseRealmFromEndpoint = (endpoint) => { // has a sideeffect of populating the basic opentelemetry config environment variables const populateEnv = () => { - if (!process.env.SPLUNK_ACCESS_TOKEN) { - process.env.SPLUNK_ACCESS_TOKEN = process.env.SIGNALFX_ACCESS_TOKEN; - } - if (!process.env.OTEL_SERVICE_NAME) { - process.env.OTEL_SERVICE_NAME = process.env.SIGNALFX_SERVICE_NAME; - } if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT && !process.env.SPLUNK_REALM) { process.env.SPLUNK_REALM = parseRealmFromEndpoint( - process.env.OTEL_EXPORTER_JAEGER_ENDPOINT ?? process.env.SIGNALFX_ENDPOINT_URL ?? '' + process.env.OTEL_EXPORTER_JAEGER_ENDPOINT ?? '' ); } - if (!process.env.OTEL_RESOURCE_ATTRIBUTES && process.env.SIGNALFX_SPAN_TAGS) { - process.env.OTEL_RESOURCE_ATTRIBUTES = process.env.SIGNALFX_SPAN_TAGS.split(',') - .map((pair) => { - const [key, value] = pair.split(':'); - return `${key}=${value}`; - }) - .join(','); - } - if (!process.env.OTEL_LOG_LEVEL && process.env.SIGNALFX_TRACING_DEBUG) { - process.env.OTEL_LOG_LEVEL = !!process.env.SIGNALFX_TRACING_DEBUG ? 'DEBUG' : 'INFO'; - } }; const logConfig = () => { console.log(