@gasket/plugin-elastic-apm 7.3.0-canary.4 → 7.3.1

package/README.md

@@ -4,38 +4,32 @@ Adds Elastic APM instrumentation to your application
 
 ## Installation
 
-#### New apps
-
 ```
-gasket create <app-name> --plugins @gasket/plugin-elastic-apm
+npm i @gasket/plugin-elastic-apm
 ```
 
-#### Existing apps
+Update your `gasket` file plugin configuration:
 
-```
-npm install @gasket/plugin-elastic-apm elastic-apm-node
-```
+```diff
+// gasket.js
 
-Modify `plugins` section of your `gasket.config.js`:
++ import pluginElasticApm from '@gasket/plugin-elastic-apm';
 
-```diff
-module.exports = {
-  plugins: {
-    add: [
-+      '@gasket/plugin-elastic-apm'
-    ]
-  }
-}
+export default makeGasket({
+  plugins: [
++   pluginElasticApm
+  ]
+});
 ```
 
-Add a `--require` flag to a `package.json` start script:
+Add `NODE_OPTIONS=--import=./setup.js` to the `package.json` start script:
 
 ```diff
   "scripts": {
-    "build": "gasket build",
--   "start": "gasket start",
-+   "start": "gasket start --require ./setup.js",
-    "local": "gasket local"
+    "build": "next build",
+-   "start": "next start",
++   "start": "NODE_OPTIONS=--import=./setup.js next start",
+    "local": "next dev"
   }
 ```
 
@@ -43,20 +37,22 @@ Add a `setup.js` script to the root of your app
 
 ```
 // setup.js
-require('dotenv').config();
+import apm from 'elastic-apm-node';
 
-require('elastic-apm-node').start({
+// Elastic APM setup
+apm.start({
   serviceName: 'my-service-name',
+  captureHeaders: false,
   secretToken: process.env.ELASTIC_APM_SECRET_TOKEN,
   serverUrl: process.env.ELASTIC_APM_SERVER_URL
-  // any additional configurations options
+  // additional configuration options
 });
 ```
 
 ## Configuration
 
 The [start recommendations] for the APM agent are to require it as early as
-possible in your app. For Gasket apps, using `--require ./setup.js`
+possible in your app. For Gasket apps, using `NODE_OPTIONS=--import=./setup.js`
 will accomplish this. To configure the APM agent, set the environment variables
 described in the [configuration options documentation].
 
@@ -64,11 +60,28 @@ In particular, the APM server URL (`ELASTIC_APM_SERVER_URL`) and secret token
 (`ELASTIC_APM_SECRET_TOKEN`) are both required configuration. If either of these
 are not present, the APM agent will be disabled.
 
+### Dotenv
+
+If you wish to use `dotenv`, be sure it is installed and imported in `setup.js`:
+
+```
+npm i dotenv
+```
+
+```diff
+// setup.js
++ import 'dotenv/config';
+import apm from 'elastic-apm-node';
+
+// Elastic APM setup
+apm.start({
+...
+```
 
 ### Plugin Configurations
 
 The Gasket plugin provides some additional setup helpers. These can be
-configured under `elasticAPM` in the `gasket.config.js`.
+configured under `elasticAPM` in the `gasket.js`.
 
 - **`sensitiveCookies`** - (string[]) A list of sensitive cookies to filter
 
@@ -77,14 +90,14 @@ configured under `elasticAPM` in the `gasket.config.js`.
 If your application’s users send session credentials or any other sensitive
 information in their cookies, you may wish to filter them out before they are
 stored in Elasticsearch. Specify a list of cookie names to redact in
-`gasket.config.js`:
+`gasket.js`:
 
 ```js
-module.exports = {
+export default makeGasket({
   elasticAPM: {
     sensitiveCookies: ['my_jwt', 'userFullName']
   }
-};
+});
 ```
 
 #### Custom Filtering Sensitive Fields
@@ -94,17 +107,18 @@ information in their cookies, you may wish to filter them out before they are
 stored in Elasticsearch. Specify a list of cookie names to redact in
 `setup.js` using the [sanitizeFieldNames] configuration option:
 
-```
+```diff
 // setup.js
-require('dotenv').config();
+import apm from 'elastic-apm-node';
 
-require('elastic-apm-node').start({
-  ...,
-  sanitizeFieldNames: ['foo', 'bar', '*token*']
-});
+// Elastic APM setup
+apm.start({
++   sanitizeFieldNames: ['foo', 'bar', '*token*']
+...
 ```
 
 The `sanitizeFieldNames` config option can be used for:
+
 - request and response HTTP headers
 - HTTP request cookies
 - any form field captured during an `application/x-www-form-urlencoded` data request
@@ -114,9 +128,39 @@ To filter out other data, use the [APM Add Filter API].
 ### Custom Filters
 
 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
+singleton_.
+This means that you can import and configure the singleton in various
 hooks of your Gasket app, such as with the [init] or [middleware] lifecycles.
 
+## Actions
+
+### getApmTransaction
+
+Use the `getApmTransaction` action to access and decorate the current APM
+transaction. This action is available in any lifecycle hook or server-side code.
+
+```js
+// example-plugin.js
+
+export default {
+  name: 'example-plugin',
+  hooks: {
+    express(gasket, app) {
+      app.use(async (req, res, next) => {
+        const transaction = await gasket.actions.getApmTransaction(req);
+        const locale = await gasket.actions.getIntlLocale(req);
+        transaction.setLabel('locale', locale);
+      });
+    }
+  }
+}
+```
+
+In the above example, we are hooking the express lifecycle to add middleware
+to decorate the transaction.
+Calling `getApmTransaction` will also allow other plugins to decorate the
+transaction by hooking the `apmTransaction` lifecycle discussed next.
+
 ## Lifecycles
 
 ### apmTransaction
@@ -131,20 +175,22 @@ request details are as follows:
 | `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']);
+// example-plugin.js
+
+export default {
+  name: 'example-plugin',
+  hooks: {
+    apmTransaction(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] and
-will set up additional filtering, such as for sensitive cookies. If the
-`preboot` hook finds that the APM agent has not yet been started using the
-recommended `--require elastic-apm-node/start`, it will start it here. However,
-you risk not bootstrapping necessary modules with a late start.
+This plugin hooks the Gasket [configure] lifecycle to set additional filtering,
+such as for sensitive cookies.
 
 ## License
 
@@ -152,7 +198,6 @@ you risk not bootstrapping necessary modules with a late start.
 
 <!-- LINKS -->
 
-[preboot]:/packages/gasket-plugin-start/README.md#preboot
 [init]:packages/gasket-plugin-command/README.md#init
 [middleware]:/packages/gasket-plugin-express/README.md#middleware
 [configuration options documentation]:https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html

package/lib/actions.js

@@ -0,0 +1,25 @@
+const { withGasketRequest } = require('@gasket/request');
+
+/** @type {import('@gasket/core').ActionHandler<'getApmTransaction'>} */
+const getApmTransaction = withGasketRequest(
+  async function getApmTransaction(gasket, req) {
+    const apm = require('elastic-apm-node');
+
+    if (!apm?.isStarted()) {
+      return;
+    }
+
+    const transaction = apm.currentTransaction;
+    if (!transaction) {
+      return;
+    }
+
+    await gasket.exec('apmTransaction', transaction, { req });
+
+    return transaction;
+  }
+);
+
+module.exports = {
+  getApmTransaction
+};

package/lib/cookies.js

@@ -17,7 +17,7 @@ const sensitiveCookies = (config) => {
 
 /**
  * Redacts the contents of user-specified sensitive cookies
- * @type {import('./index').filterSensitiveCookies}
+ * @type {import('.').filterSensitiveCookies}
  */
 const filterSensitiveCookies = function (config) {
   return function (payload) {
@@ -25,9 +25,9 @@ const filterSensitiveCookies = function (config) {
 
     if (
       payload.context &&
-    payload.context.request &&
-    payload.context.request.headers &&
-    payload.context.request.headers.cookie
+      payload.context.request &&
+      payload.context.request.headers &&
+      payload.context.request.headers.cookie
     ) {
       let cookie = payload.context.request.headers.cookie;
       cookiesToRedact.forEach((sc) => {
@@ -41,8 +41,8 @@ const filterSensitiveCookies = function (config) {
     }
 
     if (payload.context &&
-    payload.context.request &&
-    payload.context.request.cookies
+      payload.context.request &&
+      payload.context.request.cookies
     ) {
       cookiesToRedact.forEach((sc) => {
         if (sc in payload.context.request.cookies) {

package/lib/create.js

@@ -0,0 +1,24 @@
+const { name, version, devDependencies } = require('../package.json');
+
+/** @type {import('@gasket/core').HookHandler<'create'>} */
+module.exports = function create(gasket, { pkg, files, gasketConfig }) {
+  const generatorDir = `${__dirname}/../generator`;
+
+  gasketConfig.addPlugin('pluginElasticApm', name);
+
+  pkg.add('dependencies', {
+    [name]: `^${version}`,
+    'dotenv': devDependencies.dotenv,
+    'elastic-apm-node': devDependencies['elastic-apm-node']
+  });
+
+  pkg.extend((current) => {
+    return {
+      scripts: {
+        start: `NODE_OPTIONS=--import=./setup.js ${current.scripts.start}`
+      }
+    };
+  });
+
+  files.add(`${generatorDir}/*`);
+};

package/lib/index.d.ts

@@ -1,9 +1,8 @@
-import type { IncomingMessage, ServerResponse } from 'http';
-import type { AgentConfigOptions, Transaction, Payload } from 'elastic-apm-node';
-import type { MaybeAsync, GasketConfig } from '@gasket/core';
-import type { GasketData } from '@gasket/data';
+import type { AgentConfigOptions, Transaction, Payload, Agent } from 'elastic-apm-node';
+import type { GasketConfig, Plugin, MaybeAsync } from '@gasket/core';
+import type { RequestLike, GasketRequest } from '@gasket/request';
 
-export function filterSensitiveCookies(config: GasketConfig): function(Payload): Payload;
+export function filterSensitiveCookies(config: GasketConfig): (Payload) => Payload;
 
 export interface ExtendedAgentConfigOptions extends AgentConfigOptions {
   sensitiveCookies?: Array<string>;
@@ -18,26 +17,22 @@ declare module '@gasket/core' {
     apm?: Agent;
   }
 
+  export interface GasketActions {
+    getApmTransaction(
+      req: RequestLike
+    ): Promise<Transaction | void>
+  }
+
   export interface HookExecTypes {
     apmTransaction(
       transaction: Transaction,
-      details: {
-        req: IncomingMessage;
-        res: ServerResponse & {
-          locals?: {
-            gasketData: GasketData & {
-              locale?: string;
-            };
-          };
-        };
+      context: {
+        req: GasketRequest;
       }
     ): MaybeAsync<void>;
   }
 }
 
-export default {
-  name: '@gasket/plugin-elastic-apm',
-  version: '',
-  description: '',
-  hooks: {}
-};
+declare const plugin: Plugin;
+
+export default plugin;

package/lib/index.js

@@ -1,14 +1,13 @@
 /// <reference types="create-gasket-app" />
 /// <reference types="@gasket/plugin-metadata" />
 
-const middleware = require('./middleware');
-const preboot = require('./preboot');
+const actions = require('./actions');
+const create = require('./create');
 const configure = require('./configure');
 const {
   name,
   version,
-  description,
-  devDependencies
+  description
 } = require('../package.json');
 
 /** @type {import('@gasket/core').Plugin} */
@@ -16,30 +15,20 @@ const plugin = {
   name,
   version,
   description,
+  actions,
   hooks: {
     configure,
-    preboot,
-    create: {
-      timing: {
-        after: ['@gasket/plugin-start']
-      },
-      handler(gasket, { pkg, files }) {
-        const generatorDir = `${__dirname}/../generator`;
-
-        pkg.add('dependencies', {
-          'elastic-apm-node': devDependencies['elastic-apm-node']
-        });
-        pkg.add('scripts', {
-          start: 'gasket start --require ./setup.js'
-        });
-
-        files.add(`${generatorDir}/*`);
-      }
-    },
-    middleware,
+    create,
     metadata(gasket, meta) {
       return {
         ...meta,
+        actions: [
+          {
+            name: 'getApmTransaction',
+            description: 'Get the APM transaction data',
+            link: 'README.md#getApmTransaction'
+          }
+        ],
         configurations: [
           {
             name: 'elasticAPM',

package/package.json

@@ -1,24 +1,12 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "7.3.0-canary.4",
+  "version": "7.3.1",
   "description": "Adds Elastic APM instrumentation to your application",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
     "lib"
   ],
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "npm run lint -- --fix",
-    "test": "npm run test:runner",
-    "test:runner": "jest test/*.test.js",
-    "test:watch": "npm run test:runner -- --watch",
-    "test:coverage": "npm run test:runner -- --coverage --coverageReporters text",
-    "posttest": "npm run lint && npm run typecheck",
-    "report": "npm run test:runner -- --coverage --coverageReporters lcov",
-    "typecheck": "tsc",
-    "typecheck:watch": "tsc --watch"
-  },
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/godaddy/gasket.git"
@@ -33,25 +21,31 @@
     "plugin"
   ],
   "author": "GoDaddy Operating Company, LLC",
-  "maintainers": [
-    "Keith Bartholomew <kbartholomew@godaddy.com>"
-  ],
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/godaddy/gasket/issues"
   },
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-elastic-apm",
+  "dependencies": {
+    "@gasket/request": "^7.3.1"
+  },
   "devDependencies": {
-    "@gasket/core": "^7.3.0-canary.4",
-    "elastic-apm-node": "^4.4.1",
-    "eslint": "^8.56.0",
-    "eslint-config-godaddy": "^7.1.0",
-    "eslint-plugin-jest": "^27.6.3",
-    "eslint-plugin-json": "^3.1.0",
-    "eslint-plugin-unicorn": "^44.0.0",
+    "@gasket/core": "^7.3.1",
+    "@gasket/plugin-metadata": "^7.3.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.19",
+    "create-gasket-app": "^7.3.2",
+    "cross-env": "^7.0.3",
+    "dotenv": "^16.4.7",
+    "elastic-apm-node": "^4.11.0",
+    "eslint": "^8.57.1",
+    "eslint-config-godaddy": "^7.1.1",
+    "eslint-config-godaddy-typescript": "^4.0.3",
+    "eslint-plugin-jest": "^28.11.0",
+    "eslint-plugin-unicorn": "^55.0.0",
     "jest": "^29.7.0",
     "nyc": "^15.1.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.7.3"
   },
   "eslintConfig": {
     "extends": [
@@ -65,10 +59,32 @@
     ],
     "rules": {
       "unicorn/filename-case": "error"
-    }
+    },
+    "overrides": [
+      {
+        "files": [
+          "lib/*.ts"
+        ],
+        "extends": [
+          "godaddy-typescript"
+        ],
+        "rules": {
+          "jsdoc/*": "off"
+        }
+      }
+    ]
   },
   "jest": {
     "testEnvironment": "node"
   },
-  "gitHead": "2abf9afba3b1d1f9a77efe01377a2e12cfeda02c"
-}
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "pnpm run lint --fix",
+    "test": "cross-env NODE_OPTIONS='--unhandled-rejections=strict' jest",
+    "test:watch": "pnpm run test --watch",
+    "test:coverage": "pnpm run test --coverage",
+    "posttest": "pnpm run lint && pnpm run typecheck",
+    "typecheck": "tsc",
+    "typecheck:watch": "tsc --watch"
+  }
+}

package/lib/middleware.js

@@ -1,40 +0,0 @@
-/// <reference types="@gasket/plugin-express" />
-
-/**
- * Middleware for customizing transactions
- * @param {import('@gasket/core').Gasket} gasket - The Gasket engine
- * @param {import('http').IncomingMessage} req - The HTTP request being handled
- * @param {import('http').ServerResponse} res - The server response
- */
-async function customizeTransaction(gasket, req, res) {
-  const apm = gasket.apm;
-
-  if (!apm?.isStarted()) {
-    return;
-  }
-
-  const transaction = apm.currentTransaction;
-  if (!transaction) {
-    return;
-  }
-
-  await gasket.exec('apmTransaction', transaction, { req, res });
-}
-
-/**
- * Add middleware to gather config details
- * @type {import('@gasket/core').HookHandler<'middleware'>}
- */
-module.exports = function middleware(gasket) {
-  return (
-    gasket.apm &&
-    async function apmTransactionMiddleware(req, res, next) {
-      try {
-        customizeTransaction(gasket, req, res);
-      } catch (error) {
-        return next(error);
-      }
-      next();
-    }
-  );
-};

package/lib/preboot.js

@@ -1,29 +0,0 @@
-/// <reference types="@gasket/plugin-start" />
-/// <reference types="@gasket/plugin-logger" />
-
-const { filterSensitiveCookies } = require('./cookies');
-
-/** @type {import('@gasket/core').HookHandler<'preboot'>} */
-module.exports = async function preboot(gasket) {
-  const { config, logger, command } = gasket;
-
-  if (command && command.id === 'local') return;
-
-  /**
-   * @type {import('elastic-apm-node')}
-   * Note: Prefer app-level dependency in case of duplicates
-   */
-  const apm = require(require.resolve('elastic-apm-node', {
-    paths: [config.root, __dirname]
-  }));
-
-  if (!apm.isStarted()) {
-    logger.warn(
-      'Elastic APM agent is not started. Use `--require ./setup.js`'
-    );
-  }
-
-  apm.addFilter(filterSensitiveCookies(config));
-
-  gasket.apm = apm;
-};