OpenTelemetry Support

.github/workflows/release.yml

@@ -83,7 +83,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/[email protected]
         with:
-          node-version: '12'
+          node-version: '16'
       - name: download release contents
         run: |
           tag=${{ github.ref }}
@@ -128,7 +128,7 @@ jobs:
           const fs = require('fs')
           const spawnSync = require('child_process').spawnSync
 
-          const executable = path.join(__dirname, 'boltzmann_' + os.arch() + '_' + os.platform()) + (os.platform() === 'win32' ? '.exe' : '')
+          const executable = path.join(__dirname, 'boltzmann_' + (os.platform() === 'darwin' ? 'x64' : os.arch()) + '_' + os.platform()) + (os.platform() === 'win32' ? '.exe' : '')
 
           if (!fs.existsSync(executable)) {
             console.error("Sorry, boltzmann is not yet supported on %s", os.platform())

.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - name: Use Node.js 12.x
+      - name: Use Node.js ${{ matrix.node_version }}
         uses: actions/[email protected]
         with:
           node-version: ${{ matrix.node_version }}

Cargo.toml

@@ -2,7 +2,7 @@
 authors = ["C J Silverio <[email protected]>", "Chris Dickinson <[email protected]>"]
 edition = "2021"
 name = "boltzmann"
-version = "0.5.3"
+version = "0.6.0"
 documentation = "https://www.boltzmann.dev/en/docs/latest/"
 description = "A scaffolder for Boltzmann.js http service projects."
 license = "Apache-2.0"

README.md

@@ -33,7 +33,7 @@ For example, to scaffold with the defaults:
 projects|⇒ npx boltzmann-cli hello
 ```
 
-A complete project is provided for you, with useful package run scripts and linting. To run: `./boltzmann.js`. And to view the response: `curl http://localhost:5000/hello/world`. Want to know more? [Check the docs!](https://www.boltzmann.dev/en/docs/latest/)
+A complete project is provided for you, with useful package run scripts and linting. To run: `./boltzmann.js`. And to view the response: `curl http://localhost:8000/hello/world`. Want to know more? [Check the docs!](https://www.boltzmann.dev/en/docs/latest/)
 
 ## Team
 

bin/checkts.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -e
+
+if [ ! -e node_modules ]; then
+  npm ci
+else
+  npm i
+fi
+
+node_modules/.bin/tsc --noEmit --project ./tsconfig-build-js.json

docs/content/reference/02-handlers.md

@@ -394,12 +394,15 @@ async function host(context) {
 ### `id`
 
 {{ changelog(version = "0.0.0") }}
+- **Changed in 0.6.0:** Use `traceparent` as the `id` when available.
+{% end %}
 
 A unique string identifier for the request for tracing purposes. The value is
 drawn from:
 
-1. `x-honeycomb-trace`
+1. `x-honeycomb-trace` (via Honeycomb beeline tracing)
 2. `x-request-id`
+3. `traceparent` (via Honeycomb OpenTelemetry tracing)
 3. A generated [ship name from Iain M Bank's Culture series][culture] (e.g.: `"ROU Frank Exchange Of Views"`)
 
 **Example use:**

docs/content/reference/03-middleware.md

@@ -744,9 +744,9 @@ Here is an example of the request logging:
 ```
 
 The `id` fields in logs is the value of the request-id, available on the context object as the `id`
-field. This is set by examining headers for an existing id. Boltzmann consults `x-honeycomb-trace`
-and `x-request-id` before falling back to generating a request id using a short randomly-selected
-string.
+field. This is set by examining headers for an existing id. Boltzmann consults `x-honeycomb-trace`,
+`x-request-id` and `traceparent` before falling back to generating a request id using a short
+randomly-selected string.
 
 To log from your handlers, you might write code like this:
 
@@ -773,19 +773,45 @@ Boltzmann automatically attaches one instance of [`route`](#route).
 
 ### `trace`
 
+{% changelog(version="0.0.0") %}
+- **Changed in 0.6.0:** Tracing now uses OpenTelemetry if any `OTEL_*` environment
+variable is defined
+{% end %}
+
 This middleware is added to your service if you have enabled the `honeycomb` feature.
 This feature sends trace data to the [Honeycomb](https://www.honeycomb.io) service for
 deep observability of the performance of your handlers.
 
-To configure this middleware, set the following environment variables:
-
--   `HONEYCOMB_WRITEKEY`: the honeycomb API key to use; required to enable tracing
--   `HONEYCOMB_DATASET`: the name of the dataset to send trace data to; required to enable tracing
--   `HONEYCOMB_TEAM`: optional; set this to enable links to traces from error reporting
--   `HONEYCOMB_SAMPLE_RATE`: optional; passed to `honeycomb-beeline` to set the sampling rate for events
-
-The sampling rate defaults to 1 if neither sample rate env var is set. Tracing is
-disabled if a write key and dataset are not provided; the middleware is still
-attached but does nothing in this case.
+To configure this middleware for [beeline](https://www.npmjs.com/package/honeycomb-beeline) 
+tracing, set the following environment variables:
+
+-   `HONEYCOMB_API_HOST`: (optional) the honeycomb API endpoint to use - defaults to localhost
+-   `HONEYCOMB_WRITEKEY`: the honeycomb API key to use - required to enable beeline tracing
+-   `HONEYCOMB_DATASET`: the name of the dataset to send trace data to - defaults to `nodejs`
+-   `HONEYCOMB_TEAM`: (optional) set this to enable links to traces from development error reporting
+-   `HONEYCOMB_SAMPLE_RATE`: (optional) passed to `honeycomb-beeline` to set the sampling rate for events - defaults to 1
+
+The honeycomb middleware also supports
+[OpenTelemetry](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/)
+tracing over [the OTLP http/protobuf protocol](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md).
+This is enabled if any `OTEL_*` environment variables are defined.
+
+OpenTelemetry supports many, many environment variables - they document both
+[common SDK environment variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/)
+and [OTLP exporter-specific environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md),
+and it's worth perusing all of them. However, if you are in a rush:
+
+- `HONEYCOMB_WRITEKEY`: this is still used in an OpenTelemetry configuration
+- `HONEYCOMB_DATASET`: this is also still used in an OpenTelemetry configuration
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: the API endpoint - i.e. `https://api.honeycomb.io`, or your [refinery](https://docs.honeycomb.io/manage-data-volume/refinery/) instance if using one
+
+In you really, really want to use the default OpenTelemetry configuration,
+you can set `OTEL_ENABLE=1` - this isn't meaningful for the OpenTelemetry SDKs
+or OTLP exporters but will trigger the enabling of OpenTelemetry in boltzmann.
+
+Note that OpenTelemetry tracing, while intended for use with Honeycomb, may be
+used with any OTLP tracing backend. You can do this by foregoing the setting of
+`HONEYCOMB_WRITEKEY` and setting `OTEL_EXPORTER_OTLP_HEADERS` to contain the
+alternate headers for your backend.
 
 * * *

examples/attaching-middleware/boltzmann.js

@@ -2,7 +2,15 @@
 /* eslint-disable */
 /* c8 ignore file */
 'use strict';
-// Boltzmann v0.5.3
+/**/
+// Dependencies used outside of honeycomb
+const bole = require("@entropic/bole");
+const isDev = require("are-we-dev");
+module.exports = {...module.exports,  bole, isDev };
+void ``;
+
+'use strict';
+// Boltzmann v0.6.0
 /**/
 const serviceName = _getServiceName();
 function _getServiceName() {
@@ -13,6 +21,7 @@ function _getServiceName() {
         return 'boltzmann';
     }
 }
+/**/
 void ``;
 const ships = require("culture-ships");
 void ``;
@@ -37,13 +46,11 @@ void ``;
 const { Readable } = require("stream");
 const querystring = require("querystring");
 const { promisify } = require("util");
-const isDev = require("are-we-dev");
 const fmw = require("find-my-way");
 const accepts = require("accepts");
 const { promises: fs } = require("fs");
 const crypto = require("crypto");
 const http = require("http");
-const bole = require("@entropic/bole");
 const path = require("path");
 const os = require("os");
 void ``;
@@ -111,12 +118,16 @@ async function buildMiddleware(middleware, router) {
         return rhs(await lhs);
     }, Promise.resolve(router));
 }
+function handlerSpanName(handler) {
+    return `handler: ${handler.name || '<unknown>'}`;
+}
 async function handler(context) {
     const handler = context.handler;
     // 
-        return await handler(context);
-        // 
+            return await handler(context);
+            // 
 }
+void ``;
 
 void ``;
 async function routes(handlers) {
@@ -175,6 +186,7 @@ class Context {
         this.params = {};
         this.id = String(request.headers['x-honeycomb-trace'] ||
             request.headers['x-request-id'] ||
+            request.headers['traceparent'] ||
             uuid.v4());
         this._loadSession = async () => {
             throw new Error('To use context.session, attach session middleware to your app');
@@ -998,18 +1010,28 @@ function handleCORS({ origins = isDev() ? '*' : String(process.env.CORS_ALLOW_OR
     const includesStar = originsArray.includes('*');
     return (next) => {
         return async function cors(context) {
-            const reflectedOrigin = (includesStar
-                ? '*'
-                : (originsArray.includes(String(context.headers.origin))
-                    ? context.headers.origin
-                    : false));
+            const spanAttributes = {
+                'boltzmann.http.origin': String(context.headers.origin)
+            };
+            if (honeycomb.features.beeline) {
+                beeline.addContext(spanAttributes);
+            }
+            const span = otel.trace.getSpan(otel.context.active());
+            if (span) {
+                span.setAttributes(spanAttributes);
+            }
+            if (!includesStar && !originsArray.includes(String(context.headers.origin))) {
+                throw Object.assign(new Error('Origin not allowed'), {
+                    [Symbol.for('status')]: 400
+                });
+            }
             const response = (context.method === 'OPTIONS'
                 ? Object.assign(Buffer.from(''), {
                     [Symbol.for('status')]: 204,
                 })
                 : await next(context));
             response[Symbol.for('headers')] = {
-                ...(reflectedOrigin ? { 'Access-Control-Allow-Origin': reflectedOrigin } : {}),
+                'Access-Control-Allow-Origin': includesStar ? '*' : context.headers.origin,
                 'Access-Control-Allow-Methods': [].concat(methods).join(','),
                 'Access-Control-Allow-Headers': [].concat(headers).join(',')
             };
@@ -1075,13 +1097,16 @@ function enforceInvariants() {
 
 
 void ``;
-function log({ logger = bole(process.env.SERVICE_NAME || 'boltzmann'), level = process.env.LOG_LEVEL || 'debug', stream = process.stdout } = {}) {
+function log({ logger = bole(serviceName), 
+// 
+level = process.env.LOG_LEVEL || 'debug', stream = process.stdout, } = {}) {
     if (isDev()) {
         const pretty = require('bistre')({ time: true });
         pretty.pipe(stream);
         stream = pretty;
     }
     bole.output({ level, stream });
+    void ``;
     return function logMiddleware(next) {
         return async function inner(context) {
             const result = await next(context);
@@ -1109,6 +1134,7 @@ void ``;
 
 
 void ``;
+handlePing.doNotTrace = true;
 function handlePing() {
     return (next) => (context) => {
         if (context.url.pathname === '/monitor/ping') {
@@ -1465,7 +1491,7 @@ const validate = {
  * 
  * The `validate.body` middleware applies [JSON schema]( "https://json-schema.org/") validation to incoming
  * request bodies. It intercepts the body that would be returned by
- * \[`context.body`\] and validates it against the given schema, throwing a `400 Bad Request` error on validation failure. If the body passes validation it is
+ * \[`context.body`] and validates it against the given schema, throwing a `400 Bad Request` error on validation failure. If the body passes validation it is
  * passed through.
  * 
  * `Ajv` is configured with `{useDefaults: true, allErrors: true}` by default. In
@@ -1744,9 +1770,9 @@ const middleware = {
  * ````
  * 
  * The `id` fields in logs is the value of the request-id, available on the context object as the `id`
- * field. This is set by examining headers for an existing id. Boltzmann consults `x-honeycomb-trace`
- * and `x-request-id` before falling back to generating a request id using a short randomly-selected
- * string.
+ * field. This is set by examining headers for an existing id. Boltzmann consults `x-honeycomb-trace`,
+ * `x-request-id` and `traceparent` before falling back to generating a request id using a short
+ * randomly-selected string.
  * 
  * To log from your handlers, you might write code like this:
  * 
@@ -1950,44 +1976,43 @@ module.exports = {...module.exports,  Context, main: runserver, middleware, body
   void ``;
 /* c8 ignore next */
 if (require.main === module && !process.env.TAP) {
-    function passthrough() {
-        return (next) => (context) => next(context);
-    }
-    runserver({
-        middleware: _requireOr('./middleware', [])
-            .then(_processMiddleware)
-            .then((mw) => {
-            // 
-            // 
-            const acc = [];
-            // 
-            // 
-            acc.push(handlePing);
-            // 
-            // 
-            acc.push(log);
-            // 
-            // 
-            acc.push(...mw);
-            // 
-            acc.push(handleStatus);
-            // 
-            return acc.filter(Boolean);
-        }),
-    })
-        .then((server) => {
-        server.listen(Number(process.env.PORT) || 5000, () => {
-            const addrinfo = server.address();
-            if (!addrinfo) {
-                return;
-            }
-            bole('boltzmann:server').info(`now listening on port ${typeof addrinfo == 'string' ? addrinfo : addrinfo.port}`);
+    // 
+        runserver({
+            middleware: _requireOr('./middleware', [])
+                .then(_processMiddleware)
+                .then((mw) => {
+                // 
+                // 
+                const acc = [];
+                // 
+                acc.push(handlePing);
+                // 
+                // 
+                // 
+                acc.push(log);
+                // 
+                // 
+                acc.push(...mw);
+                // 
+                acc.push(handleStatus);
+                // 
+                return acc.filter(Boolean);
+            }),
+        })
+            .then((server) => {
+            server.listen(Number(process.env.PORT) || 8000, () => {
+                const addrinfo = server.address();
+                if (!addrinfo) {
+                    return;
+                }
+                bole('boltzmann:server').info(`now listening on port ${typeof addrinfo == 'string' ? addrinfo : addrinfo.port}`);
+            });
+        })
+            .catch((err) => {
+            console.error(err.stack);
+            process.exit(1);
         });
-    })
-        .catch((err) => {
-        console.error(err.stack);
-        process.exit(1);
-    });
+        // 
 }