Track errors in JavaScript

• Node.js 18 or later.
• An Observe key that starts with obs_. Read Get an ingest key.
• Version 0.5.0 of the package. This page uses its API.

npm install @postdeploy/sdk

@postdeploy/sdk/node

Node.js servers and scripts. ESM and CommonJS. Captures uncaughtException and unhandledRejection.

@postdeploy/sdk/cloudflare

Cloudflare Workers. Wrap your handlers with wrapHandler and wrapScheduled.

Call init once, before your app starts work. Set user, tags and context inside withScope. On the Node.js entry, scope calls outside withScope have no effect.

import { init, captureException, withScope, setUser, setTag, setContext, flush } from "@postdeploy/sdk/node";

init({
  key: process.env.POSTDEPLOY_API_KEY,
  environment: "production",
  release: "1.0.0",
});

await withScope(async () => {
  setUser({ id: "user_123", email: "[email protected]" });
  setTag("plan", "pro");
  setContext("checkout", { cart_items: 3 });

  try {
    throw new Error("Payment provider timed out");
  } catch (err) {
    captureException(err, { context: { feature: "checkout" } });
  }

  await flush(2000);
});

init adds listeners for uncaughtException and unhandledRejection. After an uncaught exception, the SDK sends the event, then exits the process with code 1.

Events are sent in batches. Call flush(timeoutMs) at the end of a script or job. It resolves true when the batch is sent and false when the timeout ends first. In 0.5.0 the process waits for the full timeout, so choose a short one.

1. 1

   Step 1. Run the script.

   Terminal shell

   Copy

   POSTDEPLOY_API_KEY=obs_your_key node app.mjs

2. 2

   Step 2. Open Observe. The table shows "Error: Payment provider timed out" with its source and environment, and 1 event.

3. 3

   Step 3. If nothing arrives, test the key. 400 means the key is valid. 401 means it is not.

   Terminal shell

   Copy

   curl -s -o /dev/null -w "%{http_code}\n" -X POST https://ingest.postdeploy.dev/e/errors \
     -H "Authorization: Bearer $POSTDEPLOY_API_KEY" -d '{}'

Nothing arrives and no warning prints

In 0.5.0 a rejected key drops events without a warning, even with debug: true. Test the key with the curl command above.

flush returns false but the event arrives

The send took longer than the timeout. Pass a longer timeout, for example flush(5000).

setUser has no effect on a server

Call it inside withScope, once per request or job.

The environment is not the one in init

The key sets the environment. Use a key from a source for that environment.