Merge pull request #34 from romil-punetha/0.7.1-proposal

examples/mongodb/README.md

@@ -0,0 +1,74 @@
+# Overview
+
+OpenTelemetry Mongodb 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 modification of the Mongo example that executes multiple parallel requests that interact with a Mongodb server backend using the `mongo` npm module. The example displays traces using multiple connection methods.
+- Create Collection Query
+- Insert Document Query
+- Fetch All Documents Query
+
+
+## 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 server
+   ```
+
+ - Run the client
+
+   ```sh
+   $ # from this directory
+   $ npm run client
+   ```
+
+#### Zipkin UI
+`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-ui.png?raw=true"/></p>
+
+### Jaeger
+
+ - Run the server
+
+   ```sh
+   $ # from this directory
+   $ npm run server
+   ```
+
+ - Run the client
+
+   ```sh
+   $ # from this directory
+   $ npm run client
+   ```
+#### Jaeger UI
+
+`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-ui.png?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/mongodb/client.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const tracer = require('./tracer')('example-mongodb-http-client');
+// eslint-disable-next-line import/order
+const http = require('http');
+
+/** A function which makes requests and handles response. */
+function makeRequest() {
+  // 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.
+  const span = tracer.startSpan('makeRequest');
+
+  let queries = 0;
+  let responses = 0;
+
+  tracer.withSpan(span, () => {
+    queries += 1;
+    http.get({
+      host: 'localhost',
+      port: 8080,
+      path: '/collection/',
+    }, (response) => {
+      const body = [];
+      response.on('data', (chunk) => body.push(chunk));
+      response.on('end', () => {
+        responses += 1;
+        console.log(body.toString());
+        if (responses === queries) span.end();
+      });
+    });
+  });
+  tracer.withSpan(span, () => {
+    queries += 1;
+    http.get({
+      host: 'localhost',
+      port: 8080,
+      path: '/insert/',
+    }, (response) => {
+      const body = [];
+      response.on('data', (chunk) => body.push(chunk));
+      response.on('end', () => {
+        responses += 1;
+        console.log(body.toString());
+        if (responses === queries) span.end();
+      });
+    });
+  });
+  tracer.withSpan(span, () => {
+    queries += 1;
+    http.get({
+      host: 'localhost',
+      port: 8080,
+      path: '/get/',
+    }, (response) => {
+      const body = [];
+      response.on('data', (chunk) => body.push(chunk));
+      response.on('end', () => {
+        responses += 1;
+        console.log(body.toString());
+        if (responses === queries) span.end();
+      });
+    });
+  });
+
+  // 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();

examples/mongodb/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "mongodb-example",
+  "private": true,
+  "version": "0.7.0",
+  "description": "Example of mongodb 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",
+    "mongodb",
+    "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.7.0",
+    "@opentelemetry/exporter-jaeger": "^0.7.0",
+    "@opentelemetry/exporter-zipkin": "^0.7.0",
+    "@opentelemetry/node": "^0.7.0",
+    "@opentelemetry/plugin-http": "^0.7.0",
+    "@opentelemetry/plugin-mongodb": "^0.7.0",
+    "@opentelemetry/tracing": "^0.7.0",
+    "mongodb": "^3.5.7"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/mongodb/server.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// eslint-disable-next-line import/order
+const tracer = require('./tracer')('example-mongodb-http-server');
+const MongoClient = require('mongodb').MongoClient;
+const http = require('http');
+const url = "mongodb://localhost:27017/mydb";
+let db;
+
+/** Starts a HTTP server that receives requests on sample server port. */
+function startServer(port) {
+
+  // Connect to db
+  MongoClient.connect(url, function(err, database) {
+    if(err) throw err;
+    db = database.db("mydb");
+  });
+  // Creates a server
+  const server = http.createServer(handleRequest);
+  // Starts the server
+  server.listen(port, (err) => {
+    if (err) {
+      throw err;
+    }
+    console.log(`Node HTTP listening on ${port}`);
+  });
+}
+
+/** A function which handles requests and send response. */
+function handleRequest(request, response) {
+
+  const currentSpan = tracer.getCurrentSpan();
+  // display traceid in the terminal
+  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}`);
+  try {
+    const body = [];
+    request.on('error', (err) => console.log(err));
+    request.on('data', (chunk) => body.push(chunk));
+    request.on('end', async () => {
+      if (request.url === '/collection/') {
+        handleCreateCollection(response);
+      } else if (request.url === '/insert/') {
+         handleInsertQuery(response);
+      } else if (request.url === '/get/') {
+        handleGetQuery(response);
+      } else {
+        handleNotFound(response);
+      }
+    });
+  } catch (err) {
+    console.log(err);
+  }
+}
+
+startServer(8080);
+
+function handleInsertQuery(response) {
+  const obj = { name: "John", age: "20" };
+    db.collection("users").insertOne(obj, function(err, res) {
+    if (err) {
+      console.log('Error code:', err.code);
+      response.end(err.message);
+    } else {
+      console.log("1 document inserted");
+      response.end();
+    }
+  });
+
+}
+
+function handleGetQuery(response) {
+  db.collection("users").find({}, function(err, res) {
+    if (err) {
+      console.log('Error code:', err.code);
+      response.end(err.message);
+    } else {
+      console.log("1 document served");
+      response.end();
+    }
+  });
+
+}
+
+function handleCreateCollection(response) {
+  db.createCollection("users", function(err, res) {
+    if (err) {
+      console.log('Error code:', err.code);
+      response.end(err.message);
+    } else {
+      console.log("1 collection created");
+      response.end();
+    }
+  });
+}
+
+function handleNotFound(response) {
+  response.end('not found');
+}

examples/mongodb/tracer.js

@@ -0,0 +1,35 @@
+'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');
+
+module.exports = (serviceName) => {
+  const provider = new NodeTracerProvider({
+    plugins: {
+      mongodb: {
+        enabled: true,
+        path: "@opentelemetry/plugin-mongodb",
+        enhancedDatabaseReporting: true
+      },
+      http: {
+        enabled: true,
+        path: '@opentelemetry/plugin-http',
+      },
+    },
+  });
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(new ZipkinExporter({
+    serviceName,
+  })));
+  provider.addSpanProcessor(new SimpleSpanProcessor(new JaegerExporter({
+    serviceName,
+  })));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  provider.register();
+
+  return opentelemetry.trace.getTracer('mysql-example');
+};

package.json

@@ -40,7 +40,7 @@
     "eslint-config-airbnb-base": "^14.0.0",
     "eslint-plugin-import": "^2.19.1",
     "gts": "^1.1.0",
-    "husky": "^3.0.9",
+    "husky": "^3.1.0",
     "lerna": "^3.17.0",
     "lerna-changelog": "^1.0.0",
     "tslint": "^5.0.0",

plugins/node/opentelemetry-plugin-mongodb/README.md

@@ -45,6 +45,17 @@ const provider = new NodeTracerProvider();
 
 See [examples/mongodb](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/mongodb) for a short example.
 
+### Mongo Plugin Options
+
+Mongodb plugin has few options available to choose from. You can set the following:
+
+| Options | Type | Description |
+| ------- | ---- | ----------- |
+| [`enhancedDatabaseReporting`](https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-api/src/trace/instrumentation/Plugin.ts#L91) | `string` | If true, additional information about query parameters and results will be attached (as `attributes`) to spans representing database operations |
+
+
+
+
 ## Useful links
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>

plugins/node/opentelemetry-plugin-mongodb/src/mongodb.ts

@@ -192,13 +192,17 @@ export class MongoDBPlugin extends BasePlugin<typeof mongodb> {
     });
 
     if (command === undefined) return;
-    const query = Object.keys(command.query ?? command.q ?? command).reduce(
-      (obj, key) => {
-        obj[key] = '?';
-        return obj;
-      },
-      {} as { [key: string]: string }
-    );
+
+    // capture parameters within the query as well if enhancedDatabaseReporting is enabled.
+    const commandObj = command.query ?? command.q ?? command;
+    const query =
+      this._config?.enhancedDatabaseReporting === true
+        ? commandObj
+        : Object.keys(commandObj).reduce((obj, key) => {
+            obj[key] = '?';
+            return obj;
+          }, {} as { [key: string]: unknown });
+
     span.setAttribute('db.statement', JSON.stringify(query));
   }