feat: adding Koa instrumentation (#144)

* feat: add Koa instrumentation

chore: add tslint

chore: add standard license

chore: add npmignore

chore: initial package config

docs: initial README

chore: create initial structure

chore: adds traces to Application.use method itself (on instantiation)

feat: traces for app.use

chore: update typescript version

chore: return original layer result

chore: remove app.use span based on design

chore: refactor span attribute assignments into util

chore: add router types

feat: added tracing for koa-router functions and routes

feat: don't create koa spans without root span

feat: added base tests for Koa core and Koa router

chore: finalizing plugin

feat: added kLayerPatched check

test: creating example code for Koa plugin

chore: cleaning up code

chore: update README

chore: update README

chore: update README

chore: add async middleware tests

chore: improve sample code

Add files via upload

Add files via upload

Add files via upload

chore: add jaeger example

Add files via upload

chore: add linter to example code

chore: rename plugin to instrumentation

chore: cleaning tests/examples

Add files via upload

Add files via upload

chore: fix async example code and span timing

chore: refine test style

docs: add comments to plugin patching operations

chore: file cleanup

chore: fix code style

* fix: add eslint-plugin-headers dependency

* chore: incorporating PR comments

* Update plugins/node/opentelemetry-koa-instrumentation/src/koa.ts

Co-authored-by: Daniel Dyla <[email protected]>

* fix: more changes based on feedback

* fix: fixing linting issue

* chore: bump codecov

* chore: code style

* feat: adding test cases for nested and prefixed routers

* chore: bump version to 0.9.0

* fix: bumping core dependencies to 0.10.2

* chore: refactor test server logic

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

examples/koa/README.md

@@ -0,0 +1,76 @@
+# Overview
+
+OpenTelemetry Koa 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 in a Koa application. 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/koa/client.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// eslint-disable-next-line import/order
+const tracer = require('./tracer')('example-koa-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:8081/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/koa/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "koa-example",
+  "private": true,
+  "version": "0.9.0",
+  "description": "Example of Koa and @koa/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",
+    "lint": "eslint . --ext .js",
+    "lint:fix": "eslint . --ext .js --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js-contrib.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "koa",
+    "tracing",
+    "instrumentation"
+  ],
+  "engines": {
+    "node": ">=8"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js-contrib/issues"
+  },
+  "dependencies": {
+    "@koa/router": "^9.3.1",
+    "@opentelemetry/api": "^0.10.2",
+    "@opentelemetry/exporter-jaeger": "^0.10.2",
+    "@opentelemetry/exporter-zipkin": "^0.10.2",
+    "@opentelemetry/node": "^0.10.2",
+    "@opentelemetry/plugin-http": "^0.10.2",
+    "@opentelemetry/koa-instrumentation": "^0.9.0",
+    "@opentelemetry/tracing": "^0.10.2",
+    "axios": "^0.19.0",
+    "koa": "^2.13.0"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0",
+    "eslint": "^7.4.0"
+  }
+}

examples/koa/server.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// eslint-disable-next-line
+const tracer = require('./tracer')('example-koa-server');
+
+// Adding Koa router (if desired)
+const router = require('@koa/router')();
+const Koa = require('koa');
+
+// Setup koa
+const app = new Koa();
+const PORT = 8081;
+
+// route definitions
+router.get('/run_test', runTest)
+  .get('/post/new', addPost)
+  .get('/post/:id', showNewPost);
+
+async function setUp() {
+  app.use(noOp);
+  app.use(router.routes());
+}
+
+/**
+ *  Router functions: list, add, or show posts
+*/
+const posts = ['post 0', 'post 1', 'post 2'];
+
+function addPost(ctx) {
+  posts.push(`post ${posts.length}`);
+  const currentSpan = tracer.getCurrentSpan();
+  currentSpan.addEvent('Added post');
+  currentSpan.setAttribute('Date', new Date());
+  ctx.body = `Added post: ${posts[posts.length - 1]}`;
+  ctx.redirect('/post/3');
+}
+
+async function showNewPost(ctx) {
+  const { id } = ctx.params;
+  console.log(`showNewPost with id: ${id}`);
+  const post = posts[id];
+  if (!post) ctx.throw(404, 'Invalid post id');
+  const syntheticDelay = 500;
+  await new Promise((r) => setTimeout(r, syntheticDelay));
+  ctx.body = post;
+}
+
+function runTest(ctx) {
+  console.log('runTest');
+  const currentSpan = tracer.getCurrentSpan();
+  const { traceId } = currentSpan.context();
+  console.log(`traceid: ${traceId}`);
+  console.log(`Jaeger URL: http://localhost:16686/trace/${traceId}`);
+  console.log(`Zipkin URL: http://localhost:9411/zipkin/traces/${traceId}`);
+  ctx.body = `All posts: ${posts}`;
+  ctx.redirect('/post/new');
+}
+
+async function noOp(ctx, next) {
+  console.log('Sample basic koa middleware');
+  const syntheticDelay = 100;
+  await new Promise((r) => setTimeout(r, syntheticDelay));
+  next();
+}
+
+setUp().then(() => {
+  app.listen(PORT);
+  console.log(`Listening on http://localhost:${PORT}`);
+});

examples/koa/tracer.js

@@ -0,0 +1,38 @@
+'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: {
+      koa: {
+        enabled: true,
+        path: '@opentelemetry/koa-instrumentation',
+        enhancedDatabaseReporting: true,
+      },
+      http: {
+        enabled: true,
+        path: '@opentelemetry/plugin-http',
+      },
+    },
+  });
+
+  let exporter;
+  if (EXPORTER === 'jaeger') {
+    exporter = new JaegerExporter({ serviceName });
+  } else {
+    exporter = new ZipkinExporter({ serviceName });
+  }
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  provider.register();
+
+  return opentelemetry.trace.getTracer('koa-example');
+};

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

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

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

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

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

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