Add sendError helper to Tracer object

This new helper allows you to track an error isolatedly without a span
present in the context.

An error is passed and a callback with a span is provided to add desired
metadata to it.

package.json

@@ -12,7 +12,7 @@
     "packages/*"
   ],
   "devDependencies": {
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "@types/jest": "^26.0.19",
     "husky": "^4.3.6",
     "jest": "^26.6.3",

packages/apollo-server/package.json

@@ -5,7 +5,7 @@
   "types": "dist/index",
   "license": "MIT",
   "dependencies": {
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "apollo-server-plugin-base": "^0.10.3",
     "tslib": "^2.0.3"
   },

packages/express/package.json

@@ -5,7 +5,7 @@
   "types": "dist/index",
   "license": "MIT",
   "dependencies": {
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "tslib": "^2.0.3"
   },
   "peerDependencies": {

packages/koa/package.json

@@ -5,7 +5,7 @@
   "types": "dist/index",
   "license": "MIT",
   "dependencies": {
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "shimmer": "^1.2.1",
     "tslib": "^2.0.3"
   },

packages/nextjs/package.json

@@ -5,7 +5,7 @@
   "types": "dist/index",
   "license": "MIT",
   "dependencies": {
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "tslib": "^2.0.3"
   },
   "peerDependencies": {

packages/nodejs/.changesets/add-senderror-helper-to-tracer.md

@@ -0,0 +1,20 @@
+---
+bump: "patch"
+---
+
+Add sendError helper to Tracer object.
+
+This new helper allows you to track an error separately from any other span
+inside the current context. Or use it to set up in your own error handling to
+report errors in a catch-statement if no performance monitoring is needed.
+
+```js
+try {
+  // Do complex stuff
+} catch (error) {
+  appsignal.tracer().sendError(error, span => {
+    span.setName("daily.task"); // Set a recognizable action name
+    span.set("user_id", user_id); // Set custom tags
+  });
+}
+```

packages/nodejs/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@appsignal/core": "^1.1.4",
-    "@appsignal/types": "^2.1.3",
+    "@appsignal/types": "^2.1.5",
     "require-in-the-middle": "^5.1.0",
     "semver": "^7.3.4",
     "shimmer": "^1.2.1",

packages/nodejs/src/__tests__/tracer.test.ts

@@ -37,6 +37,48 @@ describe("Tracer", () => {
     })
   })
 
+  describe(".sendError()", () => {
+    const err = new Error("FooBarError")
+
+    it("works without metadata callback", () => {
+      tracer.sendError(err)
+    })
+
+    it("uses a RootSpan", done => {
+      tracer.sendError(err, rootSpan => {
+        expect(rootSpan).toBeInstanceOf(RootSpan)
+
+        return done()
+      })
+    })
+
+    it("assigns metadata to the span if needed", done => {
+      tracer.sendError(err, rootSpan => {
+        rootSpan.setName("foo")
+        rootSpan.setCategory("bar")
+        rootSpan.set("pod", 42)
+
+        const rootSpanData = JSON.parse(rootSpan.toJSON())
+
+        expect(rootSpanData.name).toEqual("foo")
+        expect(rootSpanData.attributes["appsignal:category"]).toEqual("bar")
+        expect(rootSpanData.attributes.pod).toEqual(42)
+
+        return done()
+      })
+    })
+
+    it("adds the given error to the span", done => {
+      tracer.sendError(err, rootSpan => {
+        const rootSpanData = JSON.parse(rootSpan.toJSON())
+
+        expect(rootSpanData.error.message).toEqual("FooBarError")
+
+        return done()
+      })
+    })
+  })
+
   describe("Span instrumentation", () => {
     it("can instrument a function (async)", async done => {
       const rootSpan = tracer.createSpan().setName(name)

packages/nodejs/src/noops/tracer.ts

@@ -29,6 +29,10 @@ export class NoopTracer implements Tracer {
     return new NoopSpan()
   }
 
+  public sendError<T>(error: Error, fn: (s: NodeSpan) => T): void {
+    return
+  }
+
   public withSpan<T>(span: NodeSpan, fn: (s: NodeSpan) => T): T {
     return fn(span)
   }

packages/nodejs/src/tracer.ts

@@ -93,6 +93,21 @@ export class BaseTracer implements Tracer {
     return activeRootSpan
   }
 
+  /**
+   * Sends an error in a newly created `RootSpan` that will be closed after
+   * the given error is added to it.
+   *
+   * The created `RootSpan` is passed as the single argument to the given function.
+   * This allows you to add arbitrary metadata to it.
+   */
+  public sendError<T>(error: Error, fn?: (s: NodeSpan) => T): void {
+    const rootSpan = new RootSpan()
+
+    rootSpan.setError(error)
+    if (fn && typeof fn === "function") fn(rootSpan)
+    rootSpan.close()
+  }
+
   /**
    * Executes a given function within the context of a given `Span`. When the
    * function has finished executing, any value returned by the given function