@gasket/plugin-elastic-apm 0.0.0-canary-20250922152503

package/EXAMPLES.md

@@ -0,0 +1,133 @@
+# Examples
+
+This document provides working examples for all exported functions and lifecycle hooks from `@gasket/plugin-elastic-apm`.
+
+## Plugin Configuration
+
+### Basic Configuration
+
+```js
+// gasket.js
+import { makeGasket } from '@gasket/core';
+import pluginElasticApm from '@gasket/plugin-elastic-apm';
+
+export default makeGasket({
+  plugins: [
+    pluginElasticApm
+  ],
+  elasticAPM: {
+    sensitiveCookies: ['sessionId', 'authToken']
+  }
+});
+```
+
+### Environment Variable Configuration
+
+```js
+// setup.js
+import 'dotenv/config';
+import apm from 'elastic-apm-node';
+
+apm.start({
+  serviceName: 'my-service',
+  secretToken: process.env.ELASTIC_APM_SECRET_TOKEN,
+  serverUrl: process.env.ELASTIC_APM_SERVER_URL
+});
+```
+
+## Actions
+
+### getApmTransaction
+
+Access and decorate the current APM transaction:
+
+```js
+// In a middleware or lifecycle
+export default {
+  name: 'my-plugin',
+  hooks: {
+    middleware(gasket, app) {
+      app.use(async (req, res, next) => {
+        const transaction = await gasket.actions.getApmTransaction(req);
+
+        if (transaction) {
+          transaction.setLabel('userId', req.user?.id);
+          transaction.setLabel('requestId', req.headers['x-request-id']);
+        }
+
+        next();
+      });
+    }
+  }
+};
+```
+
+```js
+// In Next.js API route
+// pages/api/users.js
+import gasket from '../../gasket.js';
+
+export default async function handler(req, res) {
+  const transaction = await gasket.actions.getApmTransaction(req);
+
+  if (transaction) {
+    transaction.setLabel('endpoint', '/api/users');
+  }
+
+  // Your API logic here
+  res.json({ users: [] });
+}
+```
+
+## Lifecycle Hooks
+
+### apmTransaction
+
+Customize APM transaction with additional context:
+
+```js
+// In a plugin
+export default {
+  name: 'apm-customization-plugin',
+  hooks: {
+    apmTransaction(gasket, transaction, { req }) {
+      // Add custom labels
+      transaction.setLabel('userAgent', req.headers['user-agent']);
+      transaction.setLabel('locale', req.headers['accept-language']);
+
+      // Set custom name based on route
+      if (req.route?.path) {
+        transaction.name = `${req.method} ${req.route.path}`;
+      }
+
+      // Add user context
+      if (req.user) {
+        transaction.setUser({
+          id: req.user.id,
+          email: req.user.email
+        });
+      }
+    }
+  }
+};
+```
+
+```js
+// Conditional APM decoration
+export default {
+  name: 'conditional-apm-plugin',
+  hooks: {
+    apmTransaction(gasket, transaction, { req }) {
+      // Only add expensive labels for non-health check requests
+      if (!req.path.startsWith('/health')) {
+        transaction.setLabel('expensive-operation', true);
+
+        // Add custom data based on request
+        if (req.path.startsWith('/api/')) {
+          transaction.setLabel('api-version', req.headers['api-version'] || 'v1');
+        }
+      }
+    }
+  }
+};
+```

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 GoDaddy Operating Company, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# @gasket/plugin-elastic-apm
+
+Adds Elastic APM instrumentation to your application
+
+## Installation
+
+```
+npm i @gasket/plugin-elastic-apm
+```
+
+Update your `gasket` file plugin configuration:
+
+```diff
+// gasket.js
+
++ import pluginElasticApm from '@gasket/plugin-elastic-apm';
+
+export default makeGasket({
+  plugins: [
++   pluginElasticApm
+  ]
+});
+```
+
+Add `NODE_OPTIONS=--import=./setup.js` to the `package.json` start script:
+
+```diff
+  "scripts": {
+    "build": "next build",
+-   "start": "next start",
++   "start": "NODE_OPTIONS=--import=./setup.js next start",
+    "local": "next dev"
+  }
+```
+
+Add a `setup.js` script to the root of your app
+
+```
+// setup.js
+import apm from 'elastic-apm-node';
+
+// 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
+  // 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 `NODE_OPTIONS=--import=./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.
+
+### 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.js`.
+
+- **`sensitiveCookies`** - (string[]) A list of sensitive cookies to filter
+
+#### Filtering Sensitive Cookies
+
+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.js`:
+
+```js
+export default makeGasket({
+  elasticAPM: {
+    sensitiveCookies: ['my_jwt', 'userFullName']
+  }
+});
+```
+
+#### Custom Filtering Sensitive Fields
+
+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:
+
+```diff
+// setup.js
+import apm from 'elastic-apm-node';
+
+// 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
+
+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 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);
+        next();
+      });
+    }
+  }
+}
+```
+
+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.
+
+At a minimum, the `getApmTransaction` action must be invoked to execute
+the `apmTransaction` lifecycle described below.
+This can be adjusted to only run for specific requests.
+
+```js
+export default {
+  name: 'example-plugin',
+  hooks: {
+    express(gasket, app) {
+      app.use(async (req, res, next) => {
+        // Only decorate APM transaction for non-API requests
+        if(!req.path.startsWith('/api')) {
+          await gasket.actions.getApmTransaction(req);
+        }
+        next();
+      });
+    }
+  }
+}
+```
+
+## Lifecycles
+
+### apmTransaction
+
+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 |
+|----------|-------------|
+| `req`    | The HTTP request or framework-specific wrapper around it |
+| `res`    | The HTTP response or framework-specific wrapper around it |
+
+```javascript
+// 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 [configure] lifecycle to set additional filtering,
+such as for sensitive cookies.
+
+## License
+
+[MIT](./LICENSE.md)
+
+<!-- LINKS -->
+
+[init]:/packages/gasket-core/README.md#init
+[middleware]:/packages/gasket-plugin-middleware/README.md#middleware
+[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/actions.js

@@ -0,0 +1,25 @@
+const { withGasketRequestCache } = require('@gasket/request');
+
+/** @type {import('@gasket/core').ActionHandler<'getApmTransaction'>} */
+const getApmTransaction = withGasketRequestCache(
+  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/configure.js

@@ -0,0 +1,34 @@
+/**
+ * Determines if the Elastic APM agent has sufficient config to be active
+ * @param {import('./index').ExtendedAgentConfigOptions} config Apm agent config
+ * @param {NodeJS.ProcessEnv} env Environment variables
+ * @returns {boolean} A combined config object
+ */
+const isActive = (config, env) => {
+  const { active, serverUrl, secretToken } = config;
+
+  if (active || env.ELASTIC_APM_ACTIVE) {
+    return true;
+  }
+
+  const combined = {
+    serverUrl: serverUrl || env.ELASTIC_APM_SERVER_URL,
+    secretToken: secretToken || env.ELASTIC_APM_SECRET_TOKEN
+  };
+
+  if (combined.serverUrl && combined.secretToken) {
+    return true;
+  }
+
+  return false;
+};
+
+/** @type {import('@gasket/core').HookHandler<'configure'>} */
+module.exports = function configure(gasket, config) {
+  config.elasticAPM = config.elasticAPM || {};
+
+  // eslint-disable-next-line no-process-env
+  config.elasticAPM.active = isActive(config.elasticAPM, process.env);
+
+  return { ...config };
+};

package/lib/cookies.js

@@ -0,0 +1,61 @@
+/**
+ * Returns an array of cookie names which are considered sensitive because they
+ * may contain session credential or PII
+ * @param {import('@gasket/core').GasketConfig} config the Gasket config
+ * @returns {string[]} an array of cookie names
+ */
+const sensitiveCookies = (config) => {
+  if (
+    typeof config.elasticAPM === 'undefined' ||
+    typeof config.elasticAPM.sensitiveCookies === 'undefined'
+  ) {
+    return [];
+  }
+
+  return config.elasticAPM.sensitiveCookies;
+};
+
+/**
+ * Redacts the contents of user-specified sensitive cookies
+ * @type {import('.').filterSensitiveCookies}
+ */
+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
+    ) {
+      let cookie = payload.context.request.headers.cookie;
+      cookiesToRedact.forEach((sc) => {
+        cookie = cookie.replace(
+          new RegExp(sc + '=([^;]+)'),
+          sc + '=[REDACTED]'
+        );
+      });
+
+      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;
+  };
+};
+
+module.exports = {
+  filterSensitiveCookies,
+  sensitiveCookies
+};

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

@@ -0,0 +1,38 @@
+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): (Payload) => Payload;
+
+export interface ExtendedAgentConfigOptions extends AgentConfigOptions {
+  sensitiveCookies?: Array<string>;
+}
+
+declare module '@gasket/core' {
+  export interface GasketConfig {
+    elasticAPM?: ExtendedAgentConfigOptions;
+  }
+
+  export interface Gasket {
+    apm?: Agent;
+  }
+
+  export interface GasketActions {
+    getApmTransaction(
+      req: RequestLike
+    ): Promise<Transaction | void>
+  }
+
+  export interface HookExecTypes {
+    apmTransaction(
+      transaction: Transaction,
+      context: {
+        req: import('@gasket/request').GasketRequest; // TS is getting confused with the GasketRequest from @gasket/core
+      }
+    ): MaybeAsync<void>;
+  }
+}
+
+declare const plugin: Plugin;
+
+export default plugin;

package/lib/index.js

@@ -0,0 +1,61 @@
+/// <reference types="create-gasket-app" />
+/// <reference types="@gasket/plugin-metadata" />
+
+const actions = require('./actions');
+const create = require('./create');
+const configure = require('./configure');
+const {
+  name,
+  version,
+  description
+} = require('../package.json');
+
+/** @type {import('@gasket/core').Plugin} */
+const plugin = {
+  name,
+  version,
+  description,
+  actions,
+  hooks: {
+    configure,
+    create,
+    metadata(gasket, meta) {
+      return {
+        ...meta,
+        actions: [
+          {
+            name: 'getApmTransaction',
+            description: 'Get the APM transaction data',
+            link: 'README.md#getApmTransaction'
+          }
+        ],
+        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'
+          }
+        ]
+      };
+    }
+  }
+};
+
+module.exports = plugin;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gasket/plugin-elastic-apm",
+  "version": "0.0.0-canary-20250922152503",
+  "description": "Adds Elastic APM instrumentation to your application",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "EXAMPLES.md"
+  ],
+  "repository": "godaddy/gasket.git",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "apm",
+    "elastic",
+    "gasket",
+    "plugin"
+  ],
+  "author": "GoDaddy Operating Company, LLC",
+  "license": "MIT",
+  "bugs": "https://github.com/godaddy/gasket/issues",
+  "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-elastic-apm",
+  "dependencies": {
+    "@gasket/request": "^0.0.0-canary-20250922152503"
+  },
+  "devDependencies": {
+    "dotenv": "^16.4.7",
+    "elastic-apm-node": "^4.11.0",
+    "jest": "^29.7.0",
+    "nyc": "^15.1.0",
+    "create-gasket-app": "^0.0.0-canary-20250922152503",
+    "@gasket/plugin-metadata": "^0.0.0-canary-20250922152503",
+    "@gasket/core": "^0.0.0-canary-20250922152503"
+  },
+  "jest": {
+    "testEnvironment": "node"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "pnpm run lint --fix",
+    "posttest": "pnpm run lint && pnpm run typecheck",
+    "test": "cross-env NODE_OPTIONS='--unhandled-rejections=strict' jest",
+    "test:coverage": "pnpm run test --coverage",
+    "test:watch": "pnpm run test --watch",
+    "typecheck": "tsc",
+    "typecheck:watch": "tsc --watch"
+  }
+}