Errors

Errors by Utilarium docs

Pick the way that fits your app. Each way takes about two minutes.

Get a key

Make a project on the projects page. Copy its ingest key. The key starts with ek_. We show it one time. The key is public, like a DSN: it can only send events. Free accounts have 5 projects. See the free tier.

Replace ek_... in each example with your key.

Browser: one script tag

  1. Put this tag in the <head> of your page. Put it before your other scripts.
<script
  src="https://errors.utilarium.app/sdk.js"
  data-key="ek_..."
  data-release="1.0.0"
  data-environment="production"
  async
></script>

data-release, data-environment and data-route are optional. Use data-route for a page with a fixed route, such as /company/:ticker. Without it, the SDK changes ids in the path to :id.

Test it. Run this in the browser console. The new issue shows in your project in less than one minute.

setTimeout(() => { throw new Error("Test") })

If your site has a Content-Security-Policy, add https://errors.utilarium.app to script-src and connect-src.

Browser: npm package

The package is @utilarium/errors. It is not on the public npm registry. Install it from our address.

npm install https://errors.utilarium.app/errors.tgz

Start it one time, as early as you can.

import { init, captureError } from "@utilarium/errors/browser";

init({ key: "ek_...", release: "1.0.0", environment: "production" });

For a router, give the matched route pattern: route: () => matchedPattern(). In a React error boundary, call captureError(error).

What the SDK does

  • It sets no cookie and stores nothing.
  • It sends at most 5 reports for each page load.
  • It ignores errors from browser extensions and cross-origin Script error. events.
  • It removes emails, IP addresses, long numbers and tokens from messages and stacks before they leave the page.

Cloudflare Worker

  1. Install the package (see above). Add the key as a Worker variable or secret named ERRORS_KEY.
  2. Wrap your handler.
import { withErrors } from "@utilarium/errors/worker";

export default withErrors(
  {
    key: (env) => env.ERRORS_KEY,
    release: "1.0.0",
    environment: "production",
  },
  {
    async fetch(request, env, ctx) {
      // your code
      return new Response("ok");
    },
  },
);

withErrors catches an error that your handler throws. It sends the error with ctx.waitUntil. Then it throws the error again. Your users see the same answer as before.

Hono

import { errorsOnError } from "@utilarium/errors/worker";

app.onError(errorsOnError({ key: (env) => env.ERRORS_KEY, release: "1.0.0" }));

errorsOnError reports the error with the route pattern that Hono matched, for example /users/:id. It answers 500 as Hono does. Give respond: (error, c) => c.json(...) for your own answer.

Content-Security-Policy reports

Your policy can tell us when it blocks something. The address of your project is https://errors.utilarium.app/csp/ek_....

With report-uri

Content-Security-Policy: default-src 'self'; report-uri https://errors.utilarium.app/csp/ek_...

With the Reporting API

Reporting-Endpoints: csp="https://errors.utilarium.app/csp/ek_..."
Content-Security-Policy: default-src 'self'; report-to csp

Load a page that breaks the policy. The new issue CSP script-src shows in your project, with the blocked origin. The address takes application/csp-report and application/reports+json. We keep only the origin of the blocked address.

Source maps

A built app has minified stacks. Upload the source maps of each release, and we show the original file, line and name.

  1. Build your app with source maps. Keep them out of the files you serve.
  2. Run this after each build. Use the same release name as the data-release of your script tag.
ERRORS_KEY=ek_... npx -y https://errors.utilarium.app/cli.tgz --dir dist --release 1.0.0

The path of each map is its path in the folder, without .map. It must equal the path in the stack frames of the browser. Each project keeps 50 MB of maps for 90 days.

Need help?

Use the Feedback button at the bottom of any page. Read the privacy page to see what we store.