feat: router instrumentation (#458)

Co-authored-by: Bartlomiej Obecny <[email protected]>

examples/router/README.md

@@ -0,0 +1,45 @@
+# Overview
+
+OpenTelemetry Router Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example). This example demonstrates tracing calls made to Router API. All generated spans include following attributes:
+
+- `http.route`: resolved route;
+- `router.name`: the name of the handler or middleware;
+- `router.type`: either `middleware` or `request_handler`;
+- `router.version`: `router` version running.
+
+## Setup
+
+Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html)
+or
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+First install the dependencies:
+
+```sh
+npm install
+```
+
+### Zipkin
+
+```sh
+npm run zipkin:server # Run the server
+npm run zipkin:client # Run the client in a separate terminal
+```
+
+### Jaeger
+
+```sh
+npm run jaeger:server # Run the server
+npm run jaeger:client # Run the client in a separate terminal
+```
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node>
+
+## LICENSE
+
+Apache License 2.0

examples/router/client.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// required to initialize the service name for the auto-instrumentation
+require('./tracer')('example-client');
+// eslint-disable-next-line import/order
+const http = require('http');
+
+/** A function which makes requests and handles response. */
+function makeRequest(path) {
+  // span corresponds to outgoing requests. Here, we have manually created
+  // the span, which is created to track work that happens outside of the
+  // request lifecycle entirely.
+  http.get({
+    host: 'localhost',
+    headers: {
+      accept: 'text/plain',
+    },
+    port: 8080,
+    path,
+  }, (response) => {
+    response.on('data', (chunk) => console.log(path, '::', chunk.toString('utf8')));
+    response.on('end', () => {
+      console.log(path, 'status', response.statusCode);
+    });
+  });
+
+  // The process must live for at least the interval past any traces that
+  // must be exported, or some risk being lost if they are recorded after the
+  // last export.
+  console.log('Sleeping 5 seconds before shutdown to ensure all records are flushed.');
+  setTimeout(() => { console.log('Completed.'); }, 5000);
+}
+
+makeRequest('/hello/world');
+// 404
+makeRequest('/bye/world');
+// error
+makeRequest('/err');

examples/router/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "router-example",
+  "private": true,
+  "version": "0.16.0",
+  "description": "Example of router integration with OpenTelemetry",
+  "main": "index.js",
+  "scripts": {
+    "zipkin:server": "cross-env EXPORTER=zipkin node ./server.js",
+    "zipkin:client": "cross-env EXPORTER=zipkin node ./client.js",
+    "jaeger:server": "cross-env EXPORTER=jaeger node ./server.js",
+    "jaeger:client": "cross-env EXPORTER=jaeger node ./client.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "http",
+    "tracing"
+  ],
+  "engines": {
+    "node": ">=8"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^0.18.0",
+    "@opentelemetry/exporter-jaeger": "^0.18.0",
+    "@opentelemetry/exporter-zipkin": "^0.18.0",
+    "@opentelemetry/instrumentation": "^0.18.0",
+    "@opentelemetry/instrumentation-http": "^0.18.0",
+    "@opentelemetry/instrumentation-router": "^0.16.0",
+    "@opentelemetry/node": "^0.18.0",
+    "@opentelemetry/tracing": "^0.18.0",
+    "router": "^1.3.5"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/router/server.js

@@ -0,0 +1,46 @@
+'use strict';
+
+require('./tracer')('example-router-server');
+
+// `setDefaultName` shows up in spans as the name
+const setDefaultName = (req, res, next) => {
+  req.defaultName = 'Stranger';
+  next();
+};
+
+const http = require('http');
+const Router = require('router');
+
+const router = Router();
+
+router.use(setDefaultName);
+
+router.param('name', (req, res, next, name) => {
+  req.params.name = typeof name === 'string' ? name.toUpperCase() : req.defaultName;
+  next();
+});
+
+// eslint-disable-next-line prefer-arrow-callback
+router.get('/hello/:name', function greetingHandler(req, res) {
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.end(`Hello, ${req.params.name}!`);
+});
+
+// eslint-disable-next-line prefer-arrow-callback
+router.get('/err', function erroringRoute(req, res, next) {
+  next(new Error('Broken!'));
+});
+
+// eslint-disable-next-line prefer-arrow-callback, func-names
+const server = http.createServer(function (req, res) {
+  router(req, res, (error) => {
+    if (error) {
+      res.statusCode = 500;
+    } else {
+      res.statusCode = 404;
+    }
+    res.end();
+  });
+});
+
+server.listen(8080);

examples/router/tracer.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/api');
+
+const { diag, DiagConsoleLogger, DiagLogLevel } = opentelemetry;
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.VERBOSE);
+
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const { NodeTracerProvider } = require('@opentelemetry/node');
+const { SimpleSpanProcessor, ConsoleSpanExporter } = require('@opentelemetry/tracing');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
+
+const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+const { RouterInstrumentation } = require('@opentelemetry/instrumentation-router');
+
+const Exporter = ((exporterParam) => {
+  if (typeof exporterParam === 'string') {
+    const exporterString = exporterParam.toLowerCase();
+    if (exporterString.startsWith('z')) {
+      return ZipkinExporter;
+    }
+    if (exporterString.startsWith('j')) {
+      return JaegerExporter;
+    }
+  }
+  return ConsoleSpanExporter;
+})(process.env.EXPORTER);
+
+module.exports = (serviceName) => {
+  const provider = new NodeTracerProvider();
+  registerInstrumentations({
+    tracerProvider: provider,
+    instrumentations: [
+      HttpInstrumentation,
+      RouterInstrumentation,
+    ],
+  });
+
+  const exporter = new Exporter({
+    serviceName,
+  });
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  provider.register();
+
+  return opentelemetry.trace.getTracer('router-example');
+};

plugins/node/opentelemetry-instrumentation-restify/README.md

@@ -1,6 +1,6 @@
 # OpenTelemetry Restify Instrumentation for Node.js
 
-[![Gitter chat][gitter-image]][gitter-url]
+[![NPM Published Version][npm-img]][npm-url]
 [![dependencies][dependencies-image]][dependencies-url]
 [![devDependencies][devDependencies-image]][devDependencies-url]
 [![Apache License][license-image]][license-image]
@@ -46,17 +46,18 @@ See [examples/restify](https://github.com/open-telemetry/opentelemetry-js-contri
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
-- For help or feedback on this project, join us on [gitter][gitter-url]
+- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
 
 ## License
 
 Apache 2.0 - See [LICENSE][license-url] for more information.
 
-[gitter-image]: https://badges.gitter.im/open-telemetry/opentelemetry-js.svg
-[gitter-url]: https://gitter.im/open-telemetry/opentelemetry-node?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
 [license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
-[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib/status.svg?path=packages/opentelemetry-instrumentation-restify
-[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=packages%2Fopentelemetry-instrumentation-restify
-[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib/dev-status.svg?path=packages/opentelemetry-instrumentation-restify
-[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=packages%2Fopentelemetry-instrumentation-restify&type=dev
+[dependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-contrib.svg?path=plugins%2Fnode%2Fopentelemetry-instrumentation-restify
+[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=plugins%2Fnode%2Fopentelemetry-instrumentation-restify
+[devDependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-contrib.svg?path=plugins%2Fnode%2Fopentelemetry-instrumentation-restify&type=dev
+[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=plugins%2Fnode%2Fopentelemetry-instrumentation-restify&type=dev
+[npm-url]: https://www.npmjs.com/package/@opentelemetry/instrumentation-restify
+[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-restify.svg

plugins/node/opentelemetry-instrumentation-router/.eslintignore

@@ -0,0 +1 @@
+build

plugins/node/opentelemetry-instrumentation-router/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+    "env": {
+        "mocha": true,
+        "node": true
+    },
+    ...require('../../../eslint.config.js')
+}

plugins/node/opentelemetry-instrumentation-router/.npmignore

@@ -0,0 +1,4 @@
+/bin
+/coverage
+/doc
+/test