feat: add redis plugin example

examples/redis/README.md

@@ -0,0 +1,106 @@
+# Overview
+
+OpenTelemetry Redis 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), to give observability to distributed systems.
+
+This is a simple example that demonstrates tracing calls to a Redis cache via an Express API. The example
+shows key aspects of tracing such as
+- Root Span (on Client)
+- Child Span (on Client)
+- Child Span from a Remote Parent (on Server)
+- SpanContext Propagation (from Client to Server)
+- Span Events
+- Span Attributes
+
+## Installation
+
+```sh
+$ # from this directory
+$ npm install
+```
+
+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
+
+### Zipkin
+
+ - Start redis via docker
+
+   ```sh
+   # from this directory
+   npm run docker:start
+   ```
+
+ - Run the server
+
+   ```sh
+   # from this directory
+   $ npm run zipkin:server
+   ```
+
+ - Run the client
+
+   ```sh
+   # from this directory
+   npm run zipkin:client
+   ```
+
+ - Cleanup docker
+
+   ```sh
+   # from this directory
+   npm run docker:stop
+   ```
+
+#### Zipkin UI
+`zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
+Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6)
+
+<p align="center"><img src="./images/zipkin.jpg?raw=true"/></p>
+
+### Jaeger
+
+ - Start redis via docker
+
+   ```sh
+   # from this directory
+   npm run docker:start
+   ```
+
+ - Run the server
+
+   ```sh
+   # from this directory
+   $ npm run jaeger:server
+   ```
+
+ - Run the client
+
+   ```sh
+   # from this directory
+   npm run jaeger:client
+   ```
+
+ - Cleanup docker
+
+   ```sh
+   # from this directory
+   npm run docker:stop
+   ```
+
+#### Jaeger UI
+
+`jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
+Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6)
+
+<p align="center"><img src="images/jaeger.jpg?raw=true"/></p>
+
+## 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/master/packages/opentelemetry-node>
+
+## LICENSE
+
+Apache License 2.0

examples/redis/client.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const opentelemetry = require('@opentelemetry/core');
+const types = require('@opentelemetry/types');
+const config = require('./setup');
+config.setupTracerAndExporters('redis-client-service');
+const tracer = opentelemetry.getTracer();
+const axios = require('axios').default;
+
+function makeRequest() {
+    const span = tracer.startSpan('client.makeRequest()', {
+        parent: tracer.getCurrentSpan(),
+        kind: types.SpanKind.CLIENT
+    });
+
+    tracer.withSpan(span, async () => {
+        try {
+            const res = await axios.get('http://localhost:8080/run_test');
+            span.setStatus({ code: types.CanonicalCode.OK });
+            console.log(res.statusText);
+        } catch (e) {
+            span.setStatus({ code: types.CanonicalCode.UNKNOWN, message: e.message });
+        }
+        span.end();
+        console.log('Sleeping 5 seconds before shutdown to ensure all records are flushed.')
+        setTimeout(() => { console.log('Completed.'); }, 5000);
+    });
+}
+
+makeRequest();

examples/redis/express-tracer-handlers.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const types = require('@opentelemetry/types');
+
+function getMiddlewareTracer(tracer) {
+  return function(req, res, next) {
+    const span = tracer.startSpan(`express.middleware.tracer(${req.method} ${req.path})`, {
+      parent: tracer.getCurrentSpan(),
+      kind: types.SpanKind.SERVER,
+    });
+
+    // End this span before sending out the response
+    const originalSend = res.send;
+    res.send = function send() {
+      span.end();
+      originalSend.apply(res, arguments);
+    }
+
+    tracer.withSpan(span, next);
+  }
+}
+
+function getErrorTracer(tracer) {
+  return function(err, _req, res, _next) {
+    console.log('Caught error', err.message);
+    const span = tracer.getCurrentSpan();
+    if (span) {
+      span.setStatus({ code: types.CanonicalCode.INTERNAL, message: err.message });
+    }
+    res.status(500).send(err.message);
+  }
+}
+
+module.exports = {
+  getMiddlewareTracer, getErrorTracer
+}

examples/redis/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "redis-example",
+  "private": true,
+  "version": "0.2.0",
+  "description": "Example of HTTP integration with OpenTelemetry",
+  "main": "index.js",
+  "scripts": {
+    "docker:start": "docker run -d -p 6379:6379 --name otjsredis redis:alpine",
+    "docker:stop": "docker stop otjsredis && docker rm otjsredis",
+    "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/core": "^0.2.0",
+    "@opentelemetry/exporter-jaeger": "^0.2.0",
+    "@opentelemetry/exporter-zipkin": "^0.2.0",
+    "@opentelemetry/node": "^0.2.0",
+    "@opentelemetry/plugin-http": "^0.2.0",
+    "@opentelemetry/plugin-redis": "^0.2.0",
+    "@opentelemetry/tracing": "^0.2.0",
+    "@opentelemetry/types": "^0.2.0",
+    "axios": "^0.19.0",
+    "express": "^4.17.1",
+    "redis": "^2.8.0"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/redis/server.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Setup opentelemetry tracer first so that built-in plugins can hook onto their corresponding modules
+const opentelemetry = require('@opentelemetry/core');
+const config = require('./setup');
+config.setupTracerAndExporters('redis-server-service');
+const tracer = opentelemetry.getTracer();
+
+// Require in rest of modules
+const express = require('express');
+const axios = require('axios').default;
+const tracerHandlers = require('./express-tracer-handlers');
+
+// Setup express
+const app = express();
+const PORT = 8080;
+
+/**
+ * Redis Routes are set up async since we resolve the client once it is successfully connected
+ */
+async function setupRoutes() {
+  const redis = await require('./setup-redis').redis;
+
+  app.get('/run_test', async (req, res) => {
+    const uuid = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+    await axios.get(`http://localhost:${PORT}/set?args=uuid,${uuid}`);
+    const body = await axios.get(`http://localhost:${PORT}/get?args=uuid`);
+
+    if (body.data !== uuid) {
+      throw new Error('UUID did not match!');
+    } else {
+      res.sendStatus(200);
+    }
+  });
+
+  app.get('/:cmd', (req, res) => {
+    if (!req.query.args) {
+      res.status(400).send('No args provided');
+      return;
+    }
+
+    const cmd = req.params.cmd;
+    const args = req.query.args.split(',');
+    redis[cmd].call(redis, ...args, (err, result) => {
+      if (err) {
+        res.sendStatus(400);
+      } else if(result) {
+        res.status(200).send(result);
+      } else {
+        throw new Error('Empty redis response');
+      }
+    });
+  });
+}
+
+// Setup express routes & middleware
+app.use(tracerHandlers.getMiddlewareTracer(tracer));
+setupRoutes().then(() => {
+  app.use(tracerHandlers.getErrorTracer(tracer));
+  app.listen(PORT);
+  console.log(`Listening on http://localhost:${PORT}`)
+});

examples/redis/setup-redis.js

@@ -0,0 +1,13 @@
+const redis = require('redis');
+
+const client = redis.createClient('redis://localhost:6379');
+const redisPromise = new Promise(function(resolve, reject) {
+  client.once('ready', () => {
+    resolve(client);
+  });
+  client.once('error', (error) => {
+    reject(error);
+  });
+});
+
+exports.redis = redisPromise;

examples/redis/setup.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/core');
+const { NodeTracer } = require('@opentelemetry/node');
+const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
+const EXPORTER = process.env.EXPORTER || '';
+
+function setupTracerAndExporters(service) {
+  const tracer = new NodeTracer({
+    plugins: {
+      http: {
+        enabled: true,
+      },
+      redis: {
+        enabled: true,
+      }
+    }
+  });
+
+  let exporter;
+  if (EXPORTER.toLowerCase().startsWith('z')) {
+    exporter = new ZipkinExporter({
+      serviceName: service,
+    });
+  } else {
+    exporter = new JaegerExporter({
+      serviceName: service,
+      // The default flush interval is 5 seconds.
+      flushInterval: 2000
+    });
+  }
+
+  tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the BasicTracer bindings
+  opentelemetry.initGlobalTracer(tracer);
+}
+
+exports.setupTracerAndExporters = setupTracerAndExporters;