feat: mysql support

.circleci/config.yml

@@ -2,6 +2,7 @@ version: 2
 
 node_test_env: &node_test_env
  RUN_POSTGRES_TESTS: 1
+ RUN_MYSQL_TESTS: 1
  RUN_MONGODB_TESTS: 1
  RUN_REDIS_TESTS: 1
  POSTGRES_USER: postgres
@@ -13,6 +14,10 @@ node_test_env: &node_test_env
  MONGODB_HOST: localhost
  MONGODB_PORT: 27017
  MONGODB_DB: opentelemetry-tests
+ MYSQL_USER: otel
+ MYSQL_DATABASE: circle_database
+ MYSQL_PASSWORD: secret
+ MYSQL_PORT: 3306
 
 postgres_service: &postgres_service
  image: circleci/postgres:9.6-alpine
@@ -25,6 +30,14 @@ redis_service: &redis_service
 mongo_service: &mongo_service
  image: mongo
 
+mysql_service: &mysql_service
+ image: circleci/mysql:5.7
+ environment:
+ MYSQL_ROOT_PASSWORD: rootpw
+ MYSQL_DATABASE: circle_database
+ MYSQL_USER: otel
+ MYSQL_PASSWORD: secret
+
 cache_1: &cache_1
  key: npm-cache-01-{{ .Environment.CIRCLE_JOB }}-{{ checksum "/tmp/checksums.txt" }}-1
  paths:
@@ -57,6 +70,7 @@ cache_2: &cache_2
  - packages/opentelemetry-plugin-document-load/node_modules
  - packages/opentelemetry-plugin-https/node_modules
  - packages/opentelemetry-plugin-postgres/opentelemetry-plugin-pg-pool/node_modules
+ - packages/opentelemetry-plugin-mysql/node_modules
  - packages/opentelemetry-exporter-prometheus/node_modules
 
 node_unit_tests: &node_unit_tests
@@ -157,6 +171,7 @@ jobs:
  - image: node:8
  environment: *node_test_env
  - *postgres_service
+ - *mysql_service
  - *redis_service
  - *mongo_service
  <<: *node_unit_tests
@@ -165,6 +180,7 @@ jobs:
  - image: node:10
  environment: *node_test_env
  - *postgres_service
+ - *mysql_service
  - *redis_service
  - *mongo_service
  <<: *node_unit_tests
@@ -173,6 +189,7 @@ jobs:
  - image: node:12
  environment: *node_test_env
  - *postgres_service
+ - *mysql_service
  - *redis_service
  - *mongo_service
  <<: *node_unit_tests

examples/mysql/README.md

@@ -0,0 +1,74 @@
+# Overview
+
+OpenTelemetry MySQL 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 HTTP example that executes multiple parallel requests that interact with a MySQL server backend using the `mysql` npm module. The example displays traces using multiple connection methods.
+- Direct Connection Query
+- Pool Connection Query
+- Cluster Pool Connection 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/mysql/client.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/core');
+const config = require('./setup');
+
+/**
+ * The trace instance needs to be initialized first, if you want to enable
+ * automatic tracing for built-in plugins (HTTP and MySQL in this case).
+ */
+config.setupTracerAndExporters('http-client-service');
+
+const http = require('http');
+const tracer = opentelemetry.getTracer();
+
+/** 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: '/connection/query'
+ }, (response) => {
+ let 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: '/pool/query'
+ }, (response) => {
+ let 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: '/cluster/query'
+ }, (response) => {
+ let 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/mysql/package.json

@@ -0,0 +1,45 @@
+{
+ "name": "mysql-example",
+ "private": true,
+ "version": "0.2.0",
+ "description": "Example of mysql 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://git@github.com/open-telemetry/opentelemetry-js.git"
+ },
+ "keywords": [
+ "opentelemetry",
+ "mysql",
+ "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-mysql": "^0.2.0",
+ "@opentelemetry/tracing": "^0.2.0",
+ "mysql": "*"
+ },
+ "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+ "devDependencies": {
+ "@types/mysql": "*",
+ "cross-env": "^6.0.0"
+ }
+}

examples/mysql/server.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/core');
+const config = require('./setup');
+/**
+ * The trace instance needs to be initialized first, if you want to enable
+ * automatic tracing for built-in plugins (HTTP and MySQL in this case).
+ */
+config.setupTracerAndExporters('http-mysql-server-service');
+
+const mysql = require('mysql');
+const http = require('http');
+
+const tracer = opentelemetry.getTracer();
+
+const pool = mysql.createPool({
+ host : 'localhost',
+ user : 'root',
+ password : 'secret',
+ database : 'my_db',
+});
+
+const connection = mysql.createConnection({
+ host : 'localhost',
+ user : 'root',
+ password : 'secret',
+ database : 'my_db',
+});
+
+const cluster = mysql.createPoolCluster();
+
+cluster.add({
+ host : 'localhost',
+ user : 'root',
+ password : 'secret',
+ database : 'my_db',
+})
+
+/** Starts a HTTP server that receives requests on sample server port. */
+function startServer (port) {
+ // 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 {
+ let body = [];
+ request.on('error', err => console.log(err));
+ request.on('data', chunk => body.push(chunk));
+ request.on('end', () => {
+ if (request.url === "/connection/query") {
+ handleConnectionQuery(response);
+ } else if (request.url === "/pool/query") {
+ handlePoolQuery(response);
+ } else if (request.url === "/cluster/query") {
+ handleClusterQuery(response);
+ } else {
+ handleNotFound(response);
+ }
+ });
+ } catch (err) {
+ console.log(err);
+ }
+}
+
+startServer(8080);
+
+function handlePoolQuery(response) {
+ const query = "SELECT 1 + 1 as pool_solution";
+ pool.getConnection((err, conn) => {
+ conn.query(query, (err, results, fields) => {
+ tracer.getCurrentSpan().addEvent("results");
+ if (err) {
+ console.log("Error code:", err.code);
+ response.end(err.message);
+ }
+ else {
+ response.end(`${query}: ${results[0].pool_solution}`);
+ }
+ });
+ })
+}
+
+function handleConnectionQuery(response) {
+ const query = "SELECT 1 + 1 as solution";
+ connection.query(query, (err, results, fields) => {
+ if (err) {
+ console.log("Error code:", err.code);
+ response.end(err.message);
+ }
+ else {
+ response.end(`${query}: ${results[0].solution}`);
+ }
+ });
+}
+
+function handleClusterQuery(response) {
+ const query = "SELECT 1 + 1 as cluster_solution";
+ cluster.getConnection((err, conn) => {
+ conn.query(query, (err, results, fields) => {
+ tracer.getCurrentSpan().addEvent("results");
+ if (err) {
+ console.log("Error code:", err.code);
+ response.end(err.message);
+ }
+ else {
+ response.end(`${query}: ${results[0].cluster_solution}`);
+ }
+ });
+ })
+}
+
+function handleNotFound(response) {
+ response.end("not found");
+}
+