docs: add example for express plugin open-telemetry#800 (open-telemetry#810)

* docs: add example for express plugin open-telemetry#800

* chore: add link to express example in plugin's readme

* chore: addres PR's comments

Author: vmarchaud

examples/express/README.md

@@ -0,0 +1,76 @@
+# Overview
+
+OpenTelemetry Express 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 made to Express API. The example
+shows key aspects of tracing such as
+- Root Span (on Client)
+- Child Span (on Client)
+- 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
+
+ - Run the server
+
+   ```sh
+   # from this directory
+   $ npm run zipkin:server
+   ```
+
+ - Run the client
+
+   ```sh
+   # from this directory
+   npm run zipkin:client
+   ```
+
+#### 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
+
+ - Run the server
+
+   ```sh
+   # from this directory
+   $ npm run jaeger:server
+   ```
+
+ - Run the client
+
+   ```sh
+   # from this directory
+   npm run jaeger:client
+   ```
+
+#### 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/express/client.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// eslint-disable-next-line import/order
+const tracer = require('./tracer')('example-express-client');
+const api = require('@opentelemetry/api');
+const axios = require('axios').default;
+
+function makeRequest() {
+  const span = tracer.startSpan('client.makeRequest()', {
+    parent: tracer.getCurrentSpan(),
+    kind: api.SpanKind.CLIENT,
+  });
+
+  tracer.withSpan(span, async () => {
+    try {
+      const res = await axios.get('http://localhost:8080/run_test');
+      span.setStatus({ code: api.CanonicalCode.OK });
+      console.log(res.statusText);
+    } catch (e) {
+      span.setStatus({ code: api.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/express/images/jaeger.jpg

@@ -0,0 +1,45 @@
+{
+  "name": "express-example",
+  "private": true,
+  "version": "0.4.0",
+  "description": "Example of Express 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",
+    "express",
+    "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.4.0",
+    "@opentelemetry/exporter-jaeger": "^0.4.0",
+    "@opentelemetry/exporter-zipkin": "^0.4.0",
+    "@opentelemetry/node": "^0.4.0",
+    "@opentelemetry/plugin-http": "^0.4.0",
+    "@opentelemetry/plugin-express": "^0.4.0",
+    "@opentelemetry/tracing": "^0.4.0",
+    "axios": "^0.19.0",
+    "express": "^4.17.1"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/express/images/zipkin.jpg

@@ -0,0 +1,58 @@
+'use strict';
+
+// eslint-disable-next-line
+const tracer = require('./tracer')('example-express-server');
+
+// Require in rest of modules
+const express = require('express');
+const axios = require('axios').default;
+
+// Setup express
+const app = express();
+const PORT = 8080;
+
+
+const getCrudController = () => {
+  const router = express.Router();
+  const resources = [];
+  router.get('/', (req, res) => res.send(resources));
+  router.post('/', (req, res) => {
+    resources.push(req.body);
+    return res.status(201).send(req.body);
+  });
+  return router;
+};
+
+const authMiddleware = (req, res, next) => {
+  const { authorization } = req.headers;
+  if (authorization && authorization.includes('secret_token')) {
+    next();
+  } else {
+    res.sendStatus(401);
+  }
+};
+
+async function setupRoutes() {
+  app.use(express.json());
+
+  app.get('/run_test', async (req, res) => {
+    const createdCat = await axios.post(`http://localhost:${PORT}/cats`, {
+      name: 'Tom',
+      friends: [
+        'Jerry',
+      ],
+    }, {
+      headers: {
+        Authorization: 'secret_token',
+      },
+    });
+
+    return res.status(201).send(createdCat.data);
+  });
+  app.use('/cats', authMiddleware, getCrudController());
+}
+
+setupRoutes().then(() => {
+  app.listen(PORT);
+  console.log(`Listening on http://localhost:${PORT}`);
+});

examples/express/package.json

@@ -0,0 +1,43 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/api');
+const { NodeTracerProvider } = 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 || '';
+
+
+module.exports = (serviceName) => {
+  const provider = new NodeTracerProvider({
+    plugins: {
+      express: {
+        enabled: true,
+        path: '@opentelemetry/plugin-express',
+      },
+      http: {
+        enabled: true,
+        path: '@opentelemetry/plugin-http',
+      },
+    },
+  });
+
+  let exporter;
+  if (EXPORTER.toLowerCase().startsWith('z')) {
+    exporter = new ZipkinExporter({
+      serviceName,
+    });
+  } else {
+    exporter = new JaegerExporter({
+      serviceName,
+    });
+  }
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  opentelemetry.trace.initGlobalTracerProvider(provider);
+
+  return opentelemetry.trace.getTracer('express-example');
+};

examples/express/server.js

@@ -43,6 +43,8 @@ const { NodeTracerProvider } = require('@opentelemetry/node');
 const provider = new NodeTracerProvider();
 ```
 
+See [examples/express](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/express) for a short example.
+
 ### Express Plugin Options
 
 Express plugin has few options available to choose from. You can set the following: