@gasket/plugin-elastic-apm 6.21.0 → 6.25.0

package/README.md

@@ -13,7 +13,7 @@ gasket create <app-name> --plugins @gasket/plugin-elastic-apm
 #### Existing apps
 
 ```
-npm i @gasket/plugin-elastic-apm
+npm install @gasket/plugin-elastic-apm elastic-apm-node
 ```
 
 Modify `plugins` section of your `gasket.config.js`:
@@ -28,35 +28,35 @@ module.exports = {
 }
 ```
 
-## Configuration
-
-Configurations for the plugin can be added under `elasticAPM` in the config.
-This object accepts the same properties as the Elastic APM Node.js agent. (See
-the [configuration options documentation])
+Add a `--require` flag to a `package.json` start script:
 
-#### Example configuration
-
-```js
-module.exports = {
-  plugins: {
-    add: ['@gasket/plugin-elastic-apm']
-  },
-  elasticAPM: {
-    secretToken: '****',
-    serverUrl: 'http://localhost:9200'
+```diff
+  "scripts": {
+    "build": "gasket build",
+-   "start": "gasket start",
++   "start": "gasket start --require elastic-apm-node/start",
+    "local": "gasket local"
   }
-}
 ```
 
-You may also configure the APM agent with environment variables (e.g:
-`ELASTIC_APM_SERVER_URL`) instead of using the config object. These environment
-variables are also described in the [configuration options documentation].
+## 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`
+will accomplish this. To configure the APM agent, set the environment variables
+described in the [configuration options documentation].
 
-The APM server URL (as either `elasticAPM.serverUrl` or
-`ELASTIC_APM_SERVER_URL`) and secret token (as either `elasticAPM.secretToken`
-or `ELASTIC_APM_SECRET_TOKEN`) are both required configuration fields. If either
+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.
 
+### Plugin Configurations
+
+The Gasket plugin provides some additional setup helpers. These can be
+configured under `elasticAPM` in the `gasket.config.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
@@ -72,9 +72,40 @@ module.exports = {
 };
 ```
 
+### Custom Start Configurations
+
+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:
+
+```
+// setup.js
+require('elastic-apm-node').start({
+  // any configuration options
+})
+```
+
+Then adjust your start script to require it instead:
+
+```diff
+-   "start": "gasket start --require elastic-apm-node/start",
++   "start": "gasket start --require ./setup.js",
+```
+
+### 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
+hooks of your Gasket app, such as with the [init] or [middleware] lifecycles.
+
 ## How it works
 
-This plugins hooks the [preboot] lifecycle from [@gasket/plugin-start].
+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.
 
 ## License
 
@@ -83,4 +114,8 @@ This plugins hooks the [preboot] lifecycle from [@gasket/plugin-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
+[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

package/lib/index.js

@@ -1,4 +1,7 @@
 const { filterSensitiveCookies } = require('./cookies');
+const { dependencies } = require('../package.json');
+
+const isDefined = o => typeof o !== 'undefined';
 
 /**
  * Determines if the Elastic APM agent has sufficient config to be active
@@ -29,7 +32,17 @@ module.exports = {
   hooks: {
     configure: {
       handler: async (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);
 
@@ -37,12 +50,35 @@ module.exports = {
       }
     },
     preboot: {
-      handler: async ({ config }) => {
-        require('elastic-apm-node')
-          .start({
+      handler: async (gasket) => {
+        const { config, logger } = gasket;
+
+        // prefer app-level dependency in case of duplicates
+        const apm = require(
+          require.resolve('elastic-apm-node', { paths: [config.root, __dirname] })
+        );
+
+        if (!apm.isStarted()) {
+          apm.start({
             ...config.elasticAPM
-          })
-          .addFilter(filterSensitiveCookies(config));
+          });
+          logger.notice('DEPRECATED started Elastic APM agent late. Use `--require elastic-apm-node/start`');
+        }
+
+        apm.addFilter(filterSensitiveCookies(config));
+      }
+    },
+    create: {
+      timing: {
+        after: ['@gasket/plugin-start']
+      },
+      handler(gasket, { pkg }) {
+        pkg.add('dependencies', {
+          'elastic-apm-node': dependencies['elastic-apm-node']
+        });
+        pkg.add('scripts', {
+          start: 'gasket start --require elastic-apm-node/start'
+        });
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "6.21.0",
+  "version": "6.25.0",
   "description": "Adds Elastic APM instrumentation to your application",
   "main": "lib",
   "types": "lib/index.d.ts",
@@ -43,7 +43,7 @@
     "elastic-apm-node": "^3.26.0"
   },
   "devDependencies": {
-    "@gasket/engine": "^6.21.0",
+    "@gasket/engine": "^6.24.2",
     "eslint": "^8.7.0",
     "eslint-config-godaddy": "^6.0.0",
     "eslint-plugin-jest": "^25.7.0",
@@ -68,5 +68,5 @@
   "jest": {
     "testEnvironment": "node"
   },
-  "gitHead": "75eadfdef0630769df2824936ac48e4f5d7c6ba6"
+  "gitHead": "9a1bfff9d20b3b7fd32b27024c5e51dfb67104f7"
 }