Implement heartbeats in Node.js

Implement heartbeats with a conceptually similar implementation to
that of the [Ruby][ruby] and [Elixir][elixir] integrations.

Note, however, that unlike the Ruby and Elixir implementations, the
heartbeats are sent asynchronously, in a "fire and forget" manner,
without blocking the execution of the heartbeat-wrapped function.

Author: unflxw

.changesets/add-heartbeats-support.md

@@ -0,0 +1,34 @@
+---
+bump: "patch"
+type: "add"
+---
+
+Add heartbeats support. You can send heartbeats directly from your code, to
+track the execution of certain processes:
+
+```javascript
+import { heartbeat } from "@appsignal/nodejs"
+
+function sendInvoices() {
+  // ... your code here ...
+  heartbeat("send_invoices")
+}
+```
+
+You can pass a function to `heartbeat`, to report to AppSignal both when the
+process starts, and when it finishes, allowing you to see the duration of the
+process:
+
+```javascript
+import { heartbeat } from "@appsignal/nodejs"
+
+function sendInvoices() {
+  heartbeat("send_invoices", () => {
+    // ... your code here ...
+  })
+}
+```
+
+If an exception is raised within the function, the finish event will not be
+reported to AppSignal, triggering a notification about the missing heartbeat.
+The exception will bubble outside of the heartbeat function.

src/heartbeat.ts

@@ -0,0 +1,74 @@
+import crypto from "crypto"
+import { Transmitter } from "./transmitter"
+import { Client } from "./client"
+
+export type EventKind = "start" | "finish"
+
+export type Event = {
+  name: string
+  id: string
+  kind: EventKind
+  timestamp: number
+}
+
+export class Heartbeat {
+  name: string
+  id: string
+
+  constructor(name: string) {
+    this.name = name
+    this.id = crypto.randomBytes(8).toString("hex")
+  }
+
+  public start() {
+    this.transmit(this.event("start"))
+  }
+
+  public finish() {
+    this.transmit(this.event("finish"))
+  }
+
+  private event(kind: EventKind): Event {
+    return {
+      name: this.name,
+      id: this.id,
+      kind: kind,
+      timestamp: Date.now()
+    }
+  }
+
+  private transmit(event: Event) {
+    if (Client.client === undefined || !Client.client.isActive) {
+      Client.internalLogger.debug(
+        "AppSignal not started; not sending heartbeat"
+      )
+      return
+    }
+
+    new Transmitter(
+      `${Client.config.data.loggingEndpoint}/heartbeats/json`,
+      JSON.stringify(event)
+    ).transmit().then(({status}: {status: number}) => {
+      if (status !== 200) {
+        Client.internalLogger.warn(`Failed to transmit heartbeat: status code ${status}`)
+      }
+    }).catch(({error}: {error: Error}) => {
+      Client.internalLogger.warn(`Failed to transmit heartbeat: ${error.message}`)
+    })
+  }
+}
+
+export function heartbeat(name: string): void
+export function heartbeat<T>(name: string, fn: () => T): T
+export function heartbeat<T>(name: string, fn?: () => T): T | undefined {
+  const heartbeat = new Heartbeat(name)
+  let output
+
+  if (fn) {
+    heartbeat.start()
+    output = fn()
+  }
+
+  heartbeat.finish()
+  return output
+}

src/index.ts

@@ -11,3 +11,4 @@ export { expressErrorHandler } from "./instrumentation/express/error_handler"
 export { LoggerLevel, LoggerAttributes } from "./logger"
 export { WinstonTransport } from "./winston_transport"
 export * from "./helpers"
+export { Heartbeat, heartbeat } from "./heartbeat"