@gasket/plugin-elastic-apm 6.47.0 → 7.0.0-7.0.1-canary.11.0

package/README.md

@@ -34,21 +34,36 @@ Add a `--require` flag to a `package.json` start script:
   "scripts": {
     "build": "gasket build",
 -   "start": "gasket start",
-+   "start": "gasket start --require elastic-apm-node/start",
++   "start": "gasket start --require ./setup.js",
     "local": "gasket local"
   }
 ```
 
+Add a `setup.js` script to the root of your app
+
+```
+// setup.js
+require('dotenv').config();
+
+require('elastic-apm-node').start({
+  serviceName: 'my-service-name',
+  secretToken: process.env.ELASTIC_APM_SECRET_TOKEN,
+  serverUrl: process.env.ELASTIC_APM_SERVER_URL
+  // any additional configurations 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 elastic-apm-node/start`
+possible in your app. For Gasket apps, using `--require ./setup.js`
 will accomplish this. To configure the APM agent, set the environment variables
 described in the [configuration options documentation].
 
 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.
+(`ELASTIC_APM_SECRET_TOKEN`) are both required configuration. If either of these
+are not present, the APM agent will be disabled.
+
 
 ### Plugin Configurations
 
@@ -72,26 +87,29 @@ module.exports = {
 };
 ```
 
-### Custom Start Configurations
+#### Custom Filtering Sensitive Fields
 
-For scenarios where you need to configure the start options for the APM agent,
-you can do so in a custom setup script and require it instead.
-
-For example, add a `setup.js` script to the root of your app:
+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
+`setup.js` using the [sanitizeFieldNames] configuration option:
 
 ```
 // setup.js
+require('dotenv').config();
+
 require('elastic-apm-node').start({
-  // any configuration options
-})
+  ...,
+  sanitizeFieldNames: ['foo', 'bar', '*token*']
+});
 ```
 
-Then adjust your start script to require it instead:
+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
 
-```diff
--   "start": "gasket start --require elastic-apm-node/start",
-+   "start": "gasket start --require ./setup.js",
-```
+To filter out other data, use the [APM Add Filter API].
 
 ### Custom Filters
 
@@ -103,7 +121,9 @@ hooks of your Gasket app, such as with the [init] or [middleware] 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:
+Enables customizing an APM transaction. Hooks receive the current APM
+[Transaction] and details about the request. Hooks may be asynchronous. The
+request details are as follows:
 
 | Property | Description |
 |----------|-------------|
@@ -120,11 +140,11 @@ module.exports = (gasket, transaction, { req, res }) => {
 
 ## 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
+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.
+recommended `--require elastic-apm-node/start`, it will start it here. However,
+you risk not bootstrapping necessary modules with a late start.
 
 ## License
 
@@ -138,3 +158,6 @@ However, you risk not bootstrapping necessary modules with a late start.
 [configuration options documentation]:https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html
 [start recommendations]:https://www.elastic.co/guide/en/apm/agent/nodejs/master/agent-api.html#apm-start
 [Elastic APM docs]:https://www.elastic.co/guide/en/apm/agent/nodejs/master/agent-api.html
+[sanitizeFieldNames]:https://www.elastic.co/guide/en/apm/agent/nodejs/4.x/configuration.html#sanitize-field-names
+[APM Add Filter API]:https://www.elastic.co/guide/en/apm/agent/nodejs/4.x/agent-api.html#apm-add-filter
+[Transaction]:(https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html)

package/lib/configure.js

@@ -1,7 +1,3 @@
-/// <reference types="@gasket/plugin-command" />
-
-const isDefined = (o) => typeof o !== 'undefined';
-
 /**
  * Determines if the Elastic APM agent has sufficient config to be active
  * @param {import('./index').ExtendedAgentConfigOptions} config Apm agent config
@@ -27,23 +23,10 @@ const isActive = (config, env) => {
   return false;
 };
 
-/** @type {import('@gasket/engine').HookHandler<'configure'>} */
+/** @type {import('@gasket/core').HookHandler<'configure'>} */
 module.exports = async function configure(gasket, config) {
-  const { logger } = gasket;
   config.elasticAPM = config.elasticAPM || {};
 
-  const { serverUrl, secretToken } = config.elasticAPM;
-  if (isDefined(serverUrl)) {
-    logger.notice(
-      'DEPRECATED config `elasticAPM.serverUrl`. Use env var: ELASTIC_APM_SERVER_URL'
-    );
-  }
-  if (isDefined(secretToken)) {
-    logger.notice(
-      'DEPRECATED config `elasticAPM.secretToken`. Use env var: ELASTIC_APM_SECRET_TOKEN'
-    );
-  }
-
   // eslint-disable-next-line no-process-env
   config.elasticAPM.active = isActive(config.elasticAPM, process.env);
 

package/lib/cookies.js

@@ -1,7 +1,7 @@
 /**
  * Returns an array of cookie names which are considered sensitive because they
  * may contain session credential or PII
- * @param {import('@gasket/engine').GasketConfig} config the Gasket config
+ * @param {import('@gasket/core').GasketConfig} config the Gasket config
  * @returns {string[]} an array of cookie names
  */
 const sensitiveCookies = (config) => {
@@ -21,15 +21,16 @@ const sensitiveCookies = (config) => {
  */
 const filterSensitiveCookies = function (config) {
   return function (payload) {
+    const cookiesToRedact = sensitiveCookies(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;
-
-      sensitiveCookies(config).forEach((sc) => {
+      cookiesToRedact.forEach((sc) => {
         cookie = cookie.replace(
           new RegExp(sc + '=([^;]+)'),
           sc + '=[REDACTED]'
@@ -39,6 +40,17 @@ const filterSensitiveCookies = function (config) {
       payload.context.request.headers.cookie = cookie;
     }
 
+    if (payload.context &&
+    payload.context.request &&
+    payload.context.request.cookies
+    ) {
+      cookiesToRedact.forEach((sc) => {
+        if (sc in payload.context.request.cookies) {
+          payload.context.request.cookies[sc] = '[REDACTED]';
+        }
+      });
+    }
+
     return payload;
   };
 };

package/lib/index.d.ts

@@ -1,15 +1,15 @@
 import type { IncomingMessage, ServerResponse } from 'http';
-import type { Agent, AgentConfigOptions, Transaction, Payload } from 'elastic-apm-node';
-import type { MaybeAsync, GasketConfig } from '@gasket/engine';
+import type { AgentConfigOptions, Transaction, Payload } from 'elastic-apm-node';
+import type { MaybeAsync, GasketConfig } from '@gasket/core';
 import type { GasketData } from '@gasket/data';
 
 export function filterSensitiveCookies(config: GasketConfig): function(Payload): Payload;
 
-interface ExtendedAgentConfigOptions extends AgentConfigOptions {
+export interface ExtendedAgentConfigOptions extends AgentConfigOptions {
   sensitiveCookies?: Array<string>;
 }
 
-declare module '@gasket/engine' {
+declare module '@gasket/core' {
   export interface GasketConfig {
     elasticAPM?: ExtendedAgentConfigOptions;
   }
@@ -25,10 +25,17 @@ declare module '@gasket/engine' {
         req: IncomingMessage;
         res: ServerResponse & {
           locals?: {
-            gasketData: GasketData;
+            gasketData: GasketData & {
+              locale?: string;
+            };
           };
         };
       }
     ): MaybeAsync<void>;
   }
 }
+
+export default {
+  name: '@gasket/plugin-elastic-apm',
+  hooks: {}
+};

package/lib/index.js

@@ -1,12 +1,12 @@
-/// <reference types="@gasket/cli" />
+/// <reference types="create-gasket-app" />
 /// <reference types="@gasket/plugin-metadata" />
 
 const middleware = require('./middleware');
 const preboot = require('./preboot');
 const configure = require('./configure');
-const { dependencies, name } = require('../package.json');
+const { devDependencies, name } = require('../package.json');
 
-/** @type {import('@gasket/engine').Plugin} */
+/** @type {import('@gasket/core').Plugin} */
 const plugin = {
   name,
   hooks: {
@@ -16,13 +16,17 @@ const plugin = {
       timing: {
         after: ['@gasket/plugin-start']
       },
-      handler(gasket, { pkg }) {
+      handler(gasket, { pkg, files }) {
+        const generatorDir = `${__dirname}/../generator`;
+
         pkg.add('dependencies', {
-          'elastic-apm-node': dependencies['elastic-apm-node']
+          'elastic-apm-node': devDependencies['elastic-apm-node']
         });
         pkg.add('scripts', {
-          start: 'gasket start --require elastic-apm-node/start'
+          start: 'gasket start --require ./setup.js'
         });
+
+        files.add(`${generatorDir}/*`);
       }
     },
     middleware,

package/lib/middleware.js

@@ -2,7 +2,7 @@
 
 /**
  * Middleware for customizing transactions
- * @param {import('@gasket/engine').Gasket} gasket - The Gasket engine
+ * @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
  */
@@ -23,9 +23,9 @@ async function customizeTransaction(gasket, req, res) {
 
 /**
  * Add middleware to gather config details
- * @type {import('@gasket/engine').HookHandler<'middleware'>}
+ * @type {import('@gasket/core').HookHandler<'middleware'>}
  */
-module.exports = (gasket) => {
+module.exports = function middleware(gasket) {
   return (
     gasket.apm &&
     async function apmTransactionMiddleware(req, res, next) {

package/lib/preboot.js

@@ -1,9 +1,9 @@
 /// <reference types="@gasket/plugin-start" />
-/// <reference types="@gasket/plugin-log" />
+/// <reference types="@gasket/plugin-logger" />
 
 const { filterSensitiveCookies } = require('./cookies');
 
-/** @type {import('@gasket/engine').HookHandler<'preboot'>} */
+/** @type {import('@gasket/core').HookHandler<'preboot'>} */
 module.exports = async function preboot(gasket) {
   const { config, logger, command } = gasket;
 
@@ -18,11 +18,8 @@ module.exports = async function preboot(gasket) {
   }));
 
   if (!apm.isStarted()) {
-    apm.start({
-      ...config.elasticAPM
-    });
-    logger.notice(
-      'DEPRECATED started Elastic APM agent late. Use `--require elastic-apm-node/start`'
+    logger.warn(
+      'Elastic APM agent is not started. Use `--require ./setup.js`'
     );
   }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "6.47.0",
+  "version": "7.0.0-7.0.1-canary.11.0",
   "description": "Adds Elastic APM instrumentation to your application",
-  "main": "lib",
+  "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
     "lib"
@@ -41,11 +41,9 @@
     "url": "https://github.com/godaddy/gasket/issues"
   },
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-elastic-apm",
-  "dependencies": {
-    "elastic-apm-node": "^3.50.0"
-  },
   "devDependencies": {
-    "@gasket/engine": "^6.46.8",
+    "@gasket/core": "^7.0.0-7.0.1-canary.11.0",
+    "elastic-apm-node": "^4.4.1",
     "eslint": "^8.56.0",
     "eslint-config-godaddy": "^7.1.0",
     "eslint-plugin-jest": "^27.6.3",
@@ -72,5 +70,5 @@
   "jest": {
     "testEnvironment": "node"
   },
-  "gitHead": "9feff1fa92be6b1b6ed2ab6d3028490165395c62"
+  "gitHead": "ee3641e5f9218418d54690c04456fb24b63dc339"
 }