Add backtrace_paths_matched to environment

Count how many lines in a given backtrace were modified by the
`matchBacktracePaths` configuration option, and report that count
as the `backtrace_paths_matched` entry in the environment sample
data.

This is useful for customer support purposes, allowing us to easily
tell whether some lines have been modified by backtrace path
matchers.

Author: unflxw

packages/javascript/src/__tests__/index.test.ts

@@ -101,6 +101,8 @@ describe("Appsignal", () => {
         "Error: test error",
         "    at Foo (/istheapp.js:13:10)"
       ])
+
+      expect(payload.environment.backtrace_paths_matched).toEqual("1")
     })
   })
 

packages/javascript/src/__tests__/span.test.ts

@@ -16,14 +16,46 @@ describe("Span", () => {
     })
 
     it("returns the span when no error is given", () => {
-      span.setError((undefined as unknown) as Error)
+      const result = span.setError((undefined as unknown) as Error)
       expect(span.serialize().error.message).toEqual("No error has been set")
+      expect(result).toBe(span)
     })
 
     it("returns the span when the passed object is not an error", () => {
       const event = new CloseEvent("event")
-      span.setError((event as unknown) as Error)
+      const result = span.setError((event as unknown) as Error)
       expect(span.serialize().error.message).toEqual("No error has been set")
+      expect(result).toBe(span)
+    })
+  })
+
+  describe("setEnvironment", () => {
+    it("updates the spans environment", () => {
+      span.setEnvironment({ key: "value" })
+      expect(span.serialize().environment).toEqual({ key: "value" })
+    })
+
+    it("merges the environment", () => {
+      span.setEnvironment({ key: "value" })
+      span.setEnvironment({ key2: "value2" })
+      expect(span.serialize().environment).toEqual({
+        key: "value",
+        key2: "value2"
+      })
+    })
+
+    it("returns the span when no environment is given", () => {
+      const result = span.setEnvironment(
+        (undefined as unknown) as { key: string }
+      )
+      expect(span.serialize().environment).toEqual({})
+      expect(result).toBe(span)
+    })
+
+    it("returns the span when the passed object is not an object", () => {
+      const result = span.setEnvironment((123 as unknown) as { key: string })
+      expect(span.serialize().environment).toEqual({})
+      expect(result).toBe(span)
     })
   })
 
@@ -49,6 +81,10 @@ describe("Span", () => {
         "    at track (http://thirdparty.app/script.js:1:530)",
         "    at app/bundle.js:21:10"
       ])
+
+      expect(span.serialize().environment).toMatchObject({
+        backtrace_paths_matched: "3"
+      })
     })
 
     it("cleans Safari/FF-style backtraces", () => {
@@ -70,6 +106,10 @@ describe("Span", () => {
         "track@http://thirdparty.app/script.js:1:530",
         "@app/bundle.js:21:10"
       ])
+
+      expect(span.serialize().environment).toMatchObject({
+        backtrace_paths_matched: "3"
+      })
     })
 
     it("concatenates all match groups", () => {
@@ -95,6 +135,10 @@ describe("Span", () => {
         "    at track (http://thirdparty.app/script.js:1:530)",
         "    at assets/app/bundle.js:21:10"
       ])
+
+      expect(span.serialize().environment).toMatchObject({
+        backtrace_paths_matched: "3"
+      })
     })
 
     it("tries matchers in order", () => {
@@ -119,6 +163,71 @@ describe("Span", () => {
         "Foo@app/bundle.js:13:10",
         "Bar@app/bundle.js:17:10"
       ])
+
+      expect(span.serialize().environment).toMatchObject({
+        backtrace_paths_matched: "2"
+      })
+    })
+
+    it("does not match any paths when the matcher has no match groups", () => {
+      const error = new Error("test error")
+      error.stack = [
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ].join("\n")
+
+      span.setError(error)
+      // This regex always matches the line, but contains no match groups,
+      // meaning the replacement that the matcher would do would be to an
+      // empty string.
+      //
+      // This should result in the line not being modified.
+      span.cleanBacktracePath(new RegExp(".*"))
+
+      const backtrace = span.serialize().error.backtrace
+      expect(backtrace).toEqual([
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ])
+
+      expect(span.serialize().environment).toBeUndefined()
+    })
+
+    it("does not replace the path when the match is empty", () => {
+      const error = new Error("test error")
+      error.stack = [
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ].join("\n")
+
+      span.setError(error)
+      // This regex always matches the line with an empty match group,
+      // meaning the replacement that the matcher would do would be to an
+      // empty string.
+      //
+      // This should result in the line not being modified.
+      span.cleanBacktracePath(new RegExp(".*(z*)$"))
+
+      const backtrace = span.serialize().error.backtrace
+      expect(backtrace).toEqual([
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ])
+
+      expect(span.serialize().environment).toBeUndefined()
+    })
+
+    it("does not report `backtrace_paths_matched` when no paths are matched", () => {
+      const error = new Error("test error")
+      error.stack = [
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ].join("\n")
+
+      span.setError(error)
+      span.cleanBacktracePath(new RegExp("^pancakes/(.*)$"))
+
+      const backtrace = span.serialize().error.backtrace
+      expect(backtrace).toEqual([
+        "Foo@http://localhost:8080/assets/app/bundle.js:13:10"
+      ])
+
+      expect(span.serialize().environment).toBeUndefined()
     })
   })
 })

packages/javascript/src/span.ts

@@ -91,6 +91,8 @@ export class Span extends Serializable<JSSpanData> {
       return this
     }
 
+    let linesMatched = 0
+
     this._data.error.backtrace = this._data.error.backtrace.map(line => {
       const path = extractPath(line)
       if (!path) {
@@ -109,13 +111,20 @@ export class Span extends Serializable<JSSpanData> {
 
         const relevantPath = match.slice(1).join("")
         if (relevantPath) {
+          linesMatched++
           return line.replace(path, relevantPath)
         }
       }
 
       return line
     })
 
+    if (linesMatched > 0) {
+      this.setEnvironment({
+        backtrace_paths_matched: linesMatched.toString()
+      })
+    }
+
     return this
   }
 }