@gasket/plugin-elastic-apm 6.26.1 → 6.30.0

package/README.md

@@ -99,6 +99,25 @@ According to the [Elastic APM docs], the _Elastic APM agent for Node.js is a
 singleton_. This means that you can require and configure singleton in various
 hooks of your Gasket app, such as with the [init] or [middleware] lifecycles.
 
+## Lifecycles
+
+### apmTransaction
+
+Enables customizing an APM transaction. Hooks receive the current APM [Transaction](https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html) and details about the request. Hooks may be asynchronous. The request details are as follows:
+
+| Property | Description |
+|----------|-------------|
+| `req`    | The HTTP request or framework-specific wrapper around it |
+| `res`    | The HTTP response or framework-specific wrapper around it |
+
+```javascript
+// /lifecycles/apm-transaction.js
+
+module.exports = (gasket, transaction, { req, res }) => {
+  transaction.setLabel('language', req.headers['accept-language']);
+}
+```
+
 ## How it works
 
 This plugin hooks the Gasket [preboot] lifecycle from [@gasket/plugin-start]

package/lib/index.d.ts

@@ -1,4 +1,5 @@
-import type { AgentConfigOptions } from 'elastic-apm-node';
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { AgentConfigOptions, Transaction } from 'elastic-apm-node';
 
 declare module '@gasket/engine' {
   export interface GasketConfig {
@@ -6,4 +7,14 @@ declare module '@gasket/engine' {
       sensitiveCookies?: Array<string>
     },
   }
+
+  export interface HookExecTypes {
+    apmTransaction(
+      transaction: Transaction,
+      details: {
+        req: IncomingMessage,
+        res: ServerResponse
+      }
+    ): MaybeAsync<void>
+  }
 }

package/lib/index.js

@@ -1,4 +1,5 @@
 const { filterSensitiveCookies } = require('./cookies');
+const middleware = require('./middleware');
 const { dependencies } = require('../package.json');
 
 const isDefined = o => typeof o !== 'undefined';
@@ -51,7 +52,9 @@ module.exports = {
     },
     preboot: {
       handler: async (gasket) => {
-        const { config, logger } = gasket;
+        const { config, logger, command } = gasket;
+
+        if (command && command.id === 'local') return;
 
         // prefer app-level dependency in case of duplicates
         const apm = require(
@@ -80,6 +83,31 @@ module.exports = {
           start: 'gasket start --require elastic-apm-node/start'
         });
       }
+    },
+    middleware,
+    metadata(gasket, meta) {
+      return {
+        ...meta,
+        configurations: [{
+          name: 'elasticAPM',
+          link: 'README.md#configuration',
+          description: 'Configuration to provide additional setup helpers',
+          type: 'object'
+        }, {
+          name: 'elasticAPM.sensitiveCookies',
+          link: 'README.md#configuration',
+          description: 'List of sensitive cookies to filter',
+          type: 'string[]',
+          default: '[]'
+        }],
+        lifecycles: [{
+          name: 'apmTransaction',
+          method: 'exec',
+          description: 'Modify the APM transaction',
+          link: 'README.md#apmtransaction',
+          parent: 'middleware'
+        }]
+      };
     }
   }
 };

package/lib/middleware.js

@@ -0,0 +1,33 @@
+/* eslint-disable spaced-comment */
+// @ts-check
+/// <reference types="./index" />
+/// <reference types="../../gasket-plugin-nextjs" />
+
+/**
+ * @typedef {import('@gasket/engine').Gasket} Gasket
+ * @typedef {import('http').IncomingMessage}  Request
+ * @typedef {import('http').ServerResponse}   Response
+ */
+
+const { callbackify } = require('util');
+const apm = require('elastic-apm-node');
+
+/**
+ * Middleware for customizing transactions
+ *
+ * @param {Gasket}    gasket  The Gasket engine
+ * @param {Request}   req     The HTTP request being handled
+ * @param {Response}  res     The server response
+ */
+async function customizeTransaction(gasket, req, res) {
+  const transaction = apm.currentTransaction;
+  if (!transaction) {
+    return;
+  }
+
+  await gasket.exec('apmTransaction', transaction, { req, res });
+}
+
+module.exports = (gasket) => [
+  callbackify(async (req, res) => customizeTransaction(gasket, req, res))
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "6.26.1",
+  "version": "6.30.0",
   "description": "Adds Elastic APM instrumentation to your application",
   "main": "lib",
   "types": "lib/index.d.ts",
@@ -68,5 +68,5 @@
   "jest": {
     "testEnvironment": "node"
   },
-  "gitHead": "4ae5de8292ef8695e66583a8c74e945423a00707"
+  "gitHead": "5261eb36af1fce802351cfaed11284ad48d244ee"
 }