feat: add example for postgres plugin (#542)

* feat: add example for pg plugin

* fix: typos

* Update examples/postgres/README.md

Co-Authored-By: Daniel Dyla <dyladan@users.noreply.github.com>

* Update examples/postgres/client.js

Co-Authored-By: Olivier Albertini <olivier.albertini@montreal.ca>

* Update examples/postgres/server.js

Co-Authored-By: Olivier Albertini <olivier.albertini@montreal.ca>

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>
Co-authored-by: Olivier Albertini <olivier.albertini@montreal.ca>
Co-authored-by: Mayur Kale <mayurkale@google.com>

examples/postgres/README.md

@@ -0,0 +1,105 @@
+# Overview
+
+OpenTelemetry PostgreSQL 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 HTTP request from client to server. 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 postgres 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.png?raw=true"/></p>
+
+### Jaeger
+
+ - Start postgres 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.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/postgres/client.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// set up ot
+const opentelemetry = require('@opentelemetry/core');
+const config = require('./setup');
+config.setupTracerAndExporters('postgres-client-service');
+const http = require('http');
+const tracer = opentelemetry.getTracer();
+
+function makeRequest() {
+    const span = tracer.startSpan('makeRequest');
+    const randomId = Math.floor(Math.random() * 10);
+    tracer.withSpan(span, () => {
+        console.log('Client traceId ', span.context().traceId);
+        http.get({
+            host: 'localhost',
+            port: 3000,
+            path: `/insert?id=${randomId}&text=randomstring`
+        });
+
+        http.get({
+            host: 'localhost',
+            port: 3000,
+            path: `/get?id=${randomId}`
+        });
+    });
+
+    // 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/postgres/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "postgres-example",
+  "private": true,
+  "version": "0.2.0",
+  "description": "Example of Postgres 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",
+    "docker:start": "docker run -d -p 54320:5432 --name otpostgres postgres:alpine",
+    "docker:stop": "docker stop otpostgres & docker rm otpostgres"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "postgres",
+    "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-pg": "^0.2.0",
+    "@opentelemetry/plugin-pg-pool": "^0.2.0",
+    "@opentelemetry/tracing": "^0.2.0",
+    "@opentelemetry/types": "^0.2.0",
+    "express": "^4.17.1"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0",
+    "pg": "^7.12.1"
+  }
+}

examples/postgres/server.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// set up ot
+const opentelemetry = require('@opentelemetry/core');
+const { SpanKind, CanonicalCode } = require('@opentelemetry/types');
+const config = require('./setup');
+config.setupTracerAndExporters('postgres-server-service');
+const tracer = opentelemetry.getTracer();
+
+// set up pg
+const setupPg  = require('./setupPsql');
+const pool = setupPg.startPsql();
+
+// set up express
+const express = require('express');
+const app = express();
+
+app.get('/:cmd', (req, res) => {
+  const cmd = req.path.slice(1);
+  if (!req.query.id) {
+    res.status(400).send('No id provided');
+    return;
+  }
+  let queryText = `SELECT id, text FROM test WHERE id = ${req.query.id}`;
+  if (cmd === 'insert') {
+    if (!req.query.text) {
+      res.status(400).send('No text provded');
+      return;
+    }
+    queryText = {
+      text: `INSERT INTO test (id, text) VALUES($1, $2) ON CONFLICT(id) DO UPDATE SET text=$2`,
+      values: [req.query.id, req.query.text],
+    };
+  }
+  const currentSpan = tracer.getCurrentSpan();
+  console.log(`traceid: ${currentSpan.context().traceId}`);
+  const span = tracer.startSpan(cmd, {
+    parent: currentSpan,
+    kind: SpanKind.SERVER,
+  });
+  tracer.withSpan(span, () => {
+    try {
+      pool.query(queryText, (err, ret) => {
+        if (err) throw err;
+        res.send(ret.rows);
+      });
+    } catch (e) {
+      res.status(400).send({message: e.message});
+      span.setStatus(CanonicalCode.UNKNOWN);
+    }
+    span.end();
+  });
+});
+
+// start server
+const port = 3000;
+app.listen(port, function() {
+  console.log(`Node HTTP listening on ${port}`);
+});
+

examples/postgres/setup.js

@@ -0,0 +1,48 @@
+'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: {
+      pg: {
+        enabled: true,
+        // if it can't find the module, put the absolute path since the packages are not published yet
+        path: '@opentelemetry/plugin-pg'
+      },
+      'pg-pool': {
+        enabled: true,
+        path: '@opentelemetry/plugin-pg-pool'
+      },
+      http: {
+        enabled: true,
+        path: '@opentelemetry/plugin-http'
+      }
+    }
+  });
+
+  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;

examples/postgres/setupPsql.js

@@ -0,0 +1,28 @@
+const { Pool } = require('pg');
+
+// create new pool for psql
+const CONFIG = {
+    user: process.env.POSTGRES_USER || 'postgres',
+    database: process.env.POSTGRES_DB || 'postgres',
+    host: process.env.POSTGRES_HOST || 'localhost',
+    port: process.env.POSTGRES_PORT
+      ? parseInt(process.env.POSTGRES_PORT, 10)
+      : 54320,
+  };
+
+function startPsql() {
+    let pool = new Pool(CONFIG);
+
+    pool.connect(function(err, client, release) {
+        if (err) throw err;
+        release();
+        const queryText = 'CREATE TABLE IF NOT EXISTS test(id SERIAL PRIMARY KEY, text VARCHAR(40) not null)';
+        client.query(queryText, (err, res) => {
+            if (err) throw err;
+        });
+    });
+
+    return pool;
+}
+
+exports.startPsql = startPsql;