Documentation update for nodejs

node/express/index.html

@@ -317,7 +317,7 @@ <h1>Express.js</h1>
 <li><a href="#introduction">Introduction</a></li>
 <li><a href="#references">References</a></li>
 </ul>
-<h4 id="introduction">Introduction</h4>
+<h3 id="introduction">Introduction</h3>
 <p>We provide <a href="https://expressjs.com/en/guide/using-middleware.html#middleware.application">express.js application-level middleware</a> with the following ORMs/Query-Builders:</p>
 <p><div class="user-card-container">
   <a target="_blank" href="https://google.github.io/sqlcommenter/node/knex/#express-middleware">

src/content/node/express/_index.md

@@ -11,7 +11,7 @@ tags: ["express", "express.js", "middleware", "node", "node.js"]
 - [Introduction](#introduction)
 - [References](#references)
 
-#### Introduction
+### Introduction
 
 We provide [express.js application-level middleware](https://expressjs.com/en/guide/using-middleware.html#middleware.application) with the following ORMs/Query-Builders:
 
@@ -20,7 +20,7 @@ We provide [express.js application-level middleware](https://expressjs.com/en/gu
 
 ### References
 
-Resource|URL
----|---
-express.js|https://expressjs.com/
-express.js middleware|https://expressjs.com/en/guide/using-middleware.html
+| Resource              | URL                                                  |
+| --------------------- | ---------------------------------------------------- |
+| express.js            | https://expressjs.com/                               |
+| express.js middleware | https://expressjs.com/en/guide/using-middleware.html |

src/content/node/knex/_index.md

@@ -11,22 +11,22 @@ tags: ["knex", "knex.js", "query-builder", "node", "node.js", "express", "expres
 - [Introduction](#introduction)
 - [Requirements](#requirements)
 - [Installation](#installation)
-    - [Manually](#manually)
-    - [Package manager](#package-manager)
+  - [Manually](#manually)
+  - [Package manager](#package-manager)
 - [Usage](#usage)
-    - [Plain knex wrapper](#plain-knex-wrapper)
-    - [Express middleware](#express-middleware)
+  - [Plain knex wrapper](#plain-knex-wrapper)
+  - [Express middleware](#express-middleware)
 - [Fields](#fields)
-    - [Options](#options)
-        - [`include` config](#include-config)
-        - [`options` config](#options-config)
-        - [Options examples](#options-examples)
-- [End to end examples](#end-to-examples)
-    - [Source code](#source-code)
-    - [Results](#results)
-- [References](#references)
+  - [Options](#options)
+    - [`include` config](#include-config)
+    - [`options` config](#options-config)
+    - [Options examples](#options-examples)
+- [End to end examples](#end-to-end-examples)
+  - [Source code](#source-code)
+  - [Results](#results)
+  - [References](#references)
 
-#### Introduction
+### Introduction
 
 This package is in the form of `Knex.Client.prototype.query` wrapper whose purpose is to augment a SQL statement right before execution, with
 information about the controller and user code to help correlate them with SQL statements emitted by Knex.js.
@@ -37,10 +37,10 @@ Besides plain knex.js wrapping, we also provide a wrapper for the following fram
 
 ### Requirements
 
-Name|Resource
----|---
-Knex.js|https://knexjs.org/
-Node.js|https://nodejs.org/
+| Name    | Resource            |
+| ------- | ------------------- |
+| Knex.js | https://knexjs.org/ |
+| Node.js | https://nodejs.org/ |
 
 ### Installation
 
@@ -95,12 +95,12 @@ In the database server logs, the comment's fields are:
 * values are SQL escaped i.e. `key='value'`
 * URL-quoted except for the equals(`=`) sign e.g `route='%5Epolls/%24'`. so should be URL-unquoted
 
-| Field             | Format                        | Description                                                                                          | Example                                                                 |
-|-------------------|-------------------------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
-| `db_driver`       | `<database_driver>:<version>` | URL quoted name and version of the database driver                                                   | `db_driver='knex%3A0.16.5'`                                             |
-| `route`           | `<the route used>`            | URL quoted route used to match the express.js controller                                             | `route='%5E%2Fpolls%2F`                                                 |
-| `traceparent`     | `<traceparent header>`        | URL quoted [W3C `traceparent` header](https://www.w3.org/TR/trace-context/#traceparent-header)       | `traceparent='00-3e2914ebce6af09508dd1ff1128493a8-81d09ab4d8cde7cf-01'` |
-| `tracestate`      | `<tracestate header>`         | URL quoted [W3C `tracestate` header](https://www.w3.org/TR/trace-context/#tracestate-header)         | `tracestate='rojo%253D00f067aa0ba902b7%2Ccongo%253Dt61rcWkgMzE'`        |
+| Field         | Format                        | Description                                                                                    | Example                                                                 |
+| ------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `db_driver`   | `<database_driver>:<version>` | URL quoted name and version of the database driver                                             | `db_driver='knex%3A0.16.5'`                                             |
+| `route`       | `<the route used>`            | URL quoted route used to match the express.js controller                                       | `route='%5E%2Fpolls%2F`                                                 |
+| `traceparent` | `<traceparent header>`        | URL quoted [W3C `traceparent` header](https://www.w3.org/TR/trace-context/#traceparent-header) | `traceparent='00-3e2914ebce6af09508dd1ff1128493a8-81d09ab4d8cde7cf-01'` |
+| `tracestate`  | `<tracestate header>`         | URL quoted [W3C `tracestate` header](https://www.w3.org/TR/trace-context/#tracestate-header)   | `tracestate='rojo%253D00f067aa0ba902b7%2Ccongo%253Dt61rcWkgMzE'`        |
 
 #### Options
 
@@ -115,20 +115,20 @@ wrapMainKnexAsMiddleware(Knex, include={...}, options={...});
 A map of values to be optionally included in the SQL comments.
 
 | Field       | On by default |
-|-------------|---------------|
+| ----------- | ------------- |
 | db_driver   | {{<uncheck>}} |
 | route       | {{<check>}}   |
 | traceparent | {{<uncheck>}} |
 | tracestate  | {{<uncheck>}} |
 
 ##### `options` config
 A configuration object specifying where to collect trace data from. Accepted
-fields are: TraceProvider: Should be either `OpenCensus` or `OpenTelemetry`,
+fields are: TraceProvider: Should be `OpenTelemetry`,
 indicating which library to collect trace context from.
 
-| Field         | Possible values                 |
-|---------------|---------------------------------|
-| TraceProvider | `OpenCensus` or `OpenTelemetry` |
+| Field         | Possible values |
+| ------------- | --------------- |
+| TraceProvider | `OpenTelemetry` |
 
 ##### Options examples
 
@@ -173,64 +173,7 @@ Check out a full express + opentelemetry example
 
 #### Source code
 
-{{<tabs "With OpenCensus" "With OpenTelemetry" "With Route" "With DB Driver" "With All Options Set">}}
-
-{{<highlight javascript>}}
-// In file app.js.
-const tracing = require('@opencensus/nodejs');
-const {B3Format} = require('@opencensus/propagation-b3');
-const {ZipkinTraceExporter} = require('@opencensus/exporter-zipkin');
-const Knex = require('knex'); // Knex to be wrapped say v0.0.1
-const {wrapMainKnexAsMiddleware} = require('@google-cloud/sqlcommenter-knex');
-const express = require('express');
-
-const exporter = new ZipkinTraceExporter({
-    url: process.env.ZIPKIN_TRACE_URL || 'localhost://9411/api/v2/spans',
-    serviceName: 'trace-542'
-});
-
-const b3 = new B3Format();
-const traceOptions = {
-    samplingRate: 1, // Always sample
-    propagation: b3,
-    exporter: exporter
-};
-
-// start tracing
-tracing.start(traceOptions);
-
-const knexOptions = {
-    client: 'postgresql',
-    connection: {
-        host: '127.0.0.1',
-        password: '$postgres$',
-        database: 'quickstart_nodejs'
-    }
-};
-const knex = Knex(knexOptions); // knex instance
-
-const app = express();
-const port = process.env.APP_PORT || 3000;
-
-// Use the knex+express middleware with trace attributes
-app.use(wrapMainKnexAsMiddleware(Knex, {
-    traceparent: true,
-    tracestate: true,
-    route: false
-}));
-
-app.get('/', (req, res) => res.send('Hello, sqlcommenter-nodejs!!'));
-app.get('^/polls/:param', function(req, res) {
-    knex.raw('SELECT * from polls_question').then(function(polls) {
-        const blob = JSON.stringify(polls);
-        res.send(blob);
-    }).catch(function(err) {
-        console.log(err);
-        res.send(500);
-    });
-});
-app.listen(port, () => console.log(`Application listening on ${port}`));
-{{</highlight>}}
+{{<tabs "With OpenTelemetry" "With Route" "With DB Driver" "With All Options Set">}}
 
 {{<highlight javascript>}}
 // In file app.js.
@@ -371,27 +314,27 @@ app.listen(port, () => console.log(`Application listening on ${port}`));
 
 {{<highlight javascript>}}
 // In file app.js.
-const tracing = require('@opencensus/nodejs');
-const {B3Format} = require('@opencensus/propagation-b3');
-const {ZipkinTraceExporter} = require('@opencensus/exporter-zipkin');
-const Knex = require('knex'); // Knex to be wrapped say v0.0.1
-const {wrapMainKnexAsMiddleware} = require('@google-cloud/sqlcommenter-knex');
-const express = require('express');
-
-const exporter = new ZipkinTraceExporter({
-    url: process.env.ZIPKIN_TRACE_URL || 'localhost:9411/api/v2/spans',
-    serviceName: 'trace-542'
-});
+const { NodeTracerProvider } = require("@opentelemetry/node");
+const { BatchSpanProcessor } = require("@opentelemetry/tracing");
+const {
+  TraceExporter,
+} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
 
-const b3 = new B3Format();
-const traceOptions = {
-    samplingRate: 1, // Always sample
-    propagation: b3,
-    exporter: exporter
-};
+const tracerProvider = new NodeTracerProvider();
+// Export to Google Cloud Trace
+tracerProvider.addSpanProcessor(
+  new BatchSpanProcessor(new TraceExporter({ logger }), {
+    bufferSize: 500,
+    bufferTimeout: 5 * 1000,
+  })
+);
+tracerProvider.register();
 
-// start tracing
-tracing.start(traceOptions);
+// OpenTelemetry initialization should happen before importing any libraries
+// that it instruments
+const express = require("express");
+const Knex = require("knex");
+const { wrapMainKnexAsMiddleware } = require("@google-cloud/sqlcommenter-knex");
 
 const knexOptions = {
     client: 'postgresql',
@@ -406,13 +349,21 @@ const knex = Knex(knexOptions); // knex instance
 const app = express();
 const port = process.env.APP_PORT || 3000;
 
-// Use the knex+express middleware with all attributes set
-app.use(wrapMainKnexAsMiddleware(Knex, {
-    traceparent: true,
-    tracestate: true,
-    route: true,
-    db_driver: true
-}));
+// SQLCommenter express middleware injects the route into the traces
+app.use(
+  wrapMainKnexAsMiddleware(
+    Knex,
+    {
+      traceparent: true,
+      tracestate: true,
+
+      // Optional
+      db_driver: true,
+      route: true,
+    },
+    { TraceProvider: "OpenTelemetry" }
+  )
+);
 
 app.get('/', (req, res) => res.send('Hello, sqlcommenter-nodejs!!'));
 app.get('^/polls/:param', function(req, res) {
@@ -439,7 +390,7 @@ Application listening on 3000
 
 On making a request to that server at `http://localhost:3000/polls/1000`, the PostgreSQL logs show:
 
-{{<tabs "With OpenCensus" "With Route" "With DB Driver" "With All Options Set">}}
+{{<tabs "With OpenTelemetry" "With Route" "With DB Driver" "With All Options Set">}}
 
 {{<highlight shell>}}
 2019-06-03 14:32:10.842 PDT [32004] LOG:  statement: SELECT * from polls_question 
@@ -466,6 +417,6 @@ On making a request to that server at `http://localhost:3000/polls/1000`, the Po
 #### References
 
 | Resource                               | URL                                                           |
-|----------------------------------------|---------------------------------------------------------------|
+| -------------------------------------- | ------------------------------------------------------------- |
 | @google-cloud/sqlcommenter-knex on npm | https://www.npmjs.com/package/@google-cloud/sqlcommenter-knex |
 | express.js                             | https://expressjs.com/                                        |