feat: support sourcemap resolution for *ESM* stack frames in captured APM errors (#4578)

Author: trentm

docs/reference/starting-agent.md

@@ -80,12 +80,12 @@ apm.start({
   serverUrl: 'https://...',
   secretToken: '...',
   // ...
-})
+});
 ```
 
 ```ts
 // main.ts
-import 'initapm'
+import './initapm.js';
 
 // Application code starts here.
 ```

docs/release-notes/index.md

@@ -20,6 +20,17 @@ To check for security updates, go to [Security announcements for the Elastic sta
 
 % ### Fixes [next-fixes]
 
+## Next [next]
+
+### Features and enhancements [next-features-enhancements]
+
+* Get sourcemap handling for captured exceptions to work with stack frames in
+  ES Modules (ESM). Before this, sourcemap handling would only work for stack
+  frames in CommonJS modules.
+
+### Fixes [next-fixes]
+
+
 ## 4.11.2 [4-11-2]
 **Release date:** March 17, 2025
 

examples/typescript/README.md

@@ -1,12 +1,13 @@
-This directory includes an example TypeScript project using the Elastic
-Node.js APM agent. It uses a tsconfig as recommended at
-https://github.com/tsconfig/bases#node-14-tsconfigjson
+This directory includes an example TypeScript project using the Elastic Node.js
+APM agent. It uses a tsconfig as recommended at https://github.com/tsconfig/bases#node-20-tsconfigjson
+and because `"type": "module"` is set in package.json, the built JavaScript will
+use ES Modules (i.e.  `import`).
 
 Install dependencies:
 
     npm install
 
-Compile the TypeScript ("index.ts") to JavaScript ("dist/index.js"):
+Compile the TypeScript to JavaScript ("dist/..."):
 
     npm run build
 
@@ -15,7 +16,7 @@ the top of "index.ts". (See [the docs](https://www.elastic.co/guide/en/apm/agent
 for other ways of starting the APM agent.)
 
 ```ts
-import 'elastic-apm-node/start'
+import 'elastic-apm-node/start.js'
 ```
 
 This start methods means that we need to use environment variables (or an
@@ -26,7 +27,7 @@ Configure the APM agent with values from [your Elastic Stack](https://www.elasti
     export ELASTIC_APM_SERVER_URL='https://...apm...cloud.es.io:443'
     export ELASTIC_APM_SECRET_TOKEN='...'
     export ELASTIC_APM_USE_PATH_AS_TRANSACTION_NAME=true
-    node dist/index.js
+    node --experimental-loader=elastic-apm-node/loader.mjs dist/index.js
 
 This simple script creates an HTTP server and makes a single request to it.
 If things work properly, you should see a trace with a single HTTP transaction

examples/typescript/index.ts

@@ -4,10 +4,10 @@
  * compliance with the BSD 2-Clause License.
  */
 
-// Be sure to import and *start* the agent before other imports.
-import 'elastic-apm-node/start'
+// Be sure to import and *start* the APM agent before other imports.
+import 'elastic-apm-node/start.js'
 
-import http from 'http'
+import * as http from 'http'
 
 // Create an HTTP server listening at port 3000.
 const server = http.createServer((req, res) => {

examples/typescript/package.json

@@ -1,16 +1,17 @@
 {
   "name": "elastic-apm-node-typescript-example",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "private": true,
-  "main": "index.ts",
+  "type": "module",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "start": "node --enable-source-maps --experimental-loader=elastic-apm-node/loader.mjs dist/index.js"
   },
   "dependencies": {
-    "elastic-apm-node": "^3.37.0"
+    "elastic-apm-node": "^4.11.2"
   },
   "devDependencies": {
-    "@tsconfig/node14": "^1.0.3",
-    "typescript": "^4.7.4"
+    "@tsconfig/node20": "^20.1.5",
+    "typescript": "^5.0.4"
   }
 }

examples/typescript/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@tsconfig/node14/tsconfig.json",
+  "extends": "@tsconfig/node20/tsconfig.json",
   "compilerOptions": {
     "outDir": "dist"
   }

lib/stacktraces.js

@@ -16,6 +16,7 @@
 var fsPromises = require('fs/promises');
 var path = require('path');
 var { promisify } = require('util');
+const { fileURLToPath } = require('url');
 
 // avoid loading error-callsites until needed to avoid
 // Error.prepareStackTrace side-effects
@@ -89,6 +90,20 @@ function getCwd(log) {
   return cwd;
 }
 
+// "filePath" refers to frame.fileName(), but with the possible "file://..."
+// URL converted to a local path. An callsite in an ES module will have a
+// file URL for the `fileName`.
+//
+// This just relies on `callsite.getFileName() -> <string | null | undefined>`
+// so it works with CallSite or StackFrames (from `error-stack-parser`).
+function filePathFromCallSite(callsite) {
+  let filePath = callsite.getFileName();
+  if (filePath && filePath.startsWith('file://')) {
+    filePath = fileURLToPath(filePath);
+  }
+  return filePath;
+}
+
 // If gathering a stacktrace from the structured CallSites fails, this is
 // used as a fallback: parsing the `err.stack` *string*.
 function stackTraceFromErrStackString(log, err) {
@@ -114,7 +129,7 @@ function stackTraceFromErrStackString(log, err) {
     const cwd = getCwd(log);
     for (var i = 0; i < frames.length; i++) {
       const frame = frames[i];
-      const filename = frame.getFileName() || '';
+      const filename = filePathFromCallSite(frame) || '';
       stacktrace.push({
         filename: getRelativeFileName(filename, cwd),
         function: frame.getFunctionName(),
@@ -136,7 +151,7 @@ function isStackFrameApp(stackframe) {
   if (isStackFrameNode(stackframe)) {
     return false;
   } else {
-    const fileName = stackframe.getFileName();
+    const fileName = filePathFromCallSite(stackframe);
     if (!fileName) {
       return true;
     } else if (fileName.indexOf(NODE_MODULES_PATH_SEG) === -1) {
@@ -153,7 +168,7 @@ function isStackFrameNode(stackframe) {
   if (stackframe.isNative) {
     return true;
   } else {
-    const fileName = stackframe.getFileName();
+    const fileName = filePathFromCallSite(stackframe);
     if (!fileName) {
       return true;
     } else {
@@ -166,7 +181,7 @@ function isCallSiteApp(callsite) {
   if (isCallSiteNode(callsite)) {
     return false;
   } else {
-    const fileName = callsite.getFileName();
+    const fileName = filePathFromCallSite(callsite);
     if (!fileName) {
       return true;
     } else if (fileName.indexOf(NODE_MODULES_PATH_SEG) === -1) {
@@ -181,7 +196,7 @@ function isCallSiteNode(callsite) {
   if (callsite.isNative()) {
     return true;
   } else {
-    const fileName = callsite.getFileName();
+    const fileName = filePathFromCallSite(callsite);
     if (!fileName) {
       return true;
     } else {
@@ -244,7 +259,7 @@ async function getSourceMapConsumer(callsite) {
   if (isCallSiteNode(callsite)) {
     return null;
   } else {
-    var filename = callsite.getFileName();
+    var filename = filePathFromCallSite(callsite);
     if (!filename) {
       return null;
     } else {
@@ -277,7 +292,7 @@ async function frameFromCallSite(
   sourceLinesLibraryFrames,
 ) {
   // getFileName can return null, e.g. with a `at Generator.next (<anonymous>)` frame.
-  const filename = callsite.getFileName() || '';
+  const filename = filePathFromCallSite(callsite) || '';
   const lineno = callsite.getLineNumber();
   const colno = callsite.getColumnNumber();