@gasket/plugin-elastic-apm 7.4.8 → 7.4.9

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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "7.4.8",
+  "version": "7.4.9",
   "description": "Adds Elastic APM instrumentation to your application",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
-    "lib"
+    "lib",
+    "EXAMPLES.md"
   ],
   "repository": "godaddy/gasket.git",
   "publishConfig": {
@@ -22,16 +23,16 @@
   "bugs": "https://github.com/godaddy/gasket/issues",
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-elastic-apm",
   "dependencies": {
-    "@gasket/request": "^7.5.3"
+    "@gasket/request": "^7.5.4"
   },
   "devDependencies": {
     "dotenv": "^16.4.7",
     "elastic-apm-node": "^4.11.0",
     "jest": "^29.7.0",
     "nyc": "^15.1.0",
-    "@gasket/core": "^7.6.2",
-    "@gasket/plugin-metadata": "^7.5.3",
-    "create-gasket-app": "^7.4.12"
+    "@gasket/core": "^7.6.3",
+    "@gasket/plugin-metadata": "^7.5.4",
+    "create-gasket-app": "^7.4.13"
   },
   "jest": {
     "testEnvironment": "node"