Browser

One import where your app starts in the browser. Uncaught errors and promise rejections are reported with the clicks, navigation and requests that led to them.

4 min read

Install

bash

npm install @naijacloud/argus

Set up

Where your app starts in the browser, such as main.ts or index.js:

main.js

import { init } from '@naijacloud/argus/browser'

init({ dsn: 'https://<public key>@argus-in.naijacloud.com/<project id>' })

The DSN's key is public: it can only send data to that one source, so it's safe in browser code. For a Next.js app, use Next.js instead.

Send a test event

From a terminal:

Send a test event

bash

npx @naijacloud/argus test --dsn https://<public key>@argus-in.naijacloud.com/<project id>

Or from your app, once it's running:

Test from the page

import { captureMessage } from '@naijacloud/argus/browser'

captureMessage('Argus test event from the browser', 'info')

Either shows under Argus → Errors within a minute.

What it captures

Uncaught errors and promise rejections.
Breadcrumbs of clicks (which element was clicked, never what was typed), navigation, console, fetch and XHR.
Offline errors. Errors raised while offline are kept in localStorage (up to 30) and sent when the browser is back online. Queued errors are sent with sendBeacon when the page is closed.

Page-load and route-change traces are not recorded yet. For page views, Web Vitals and session replay, use the website script.

Report errors yourself

Errors

import { addBreadcrumb, captureException, setUser } from '@naijacloud/argus/browser'

setUser({ id: user.id })
addBreadcrumb({ category: 'checkout', message: 'Applied coupon' })

try {
  await submitOrder(cart)
} catch (err) {
  captureException(err, { tags: { step: 'payment' } })
}

Logs, metrics and traces

import { log, metrics, trace } from '@naijacloud/argus/browser'

log.warn('payment form slow', { ms: 2300 })
metrics.distribution('checkout.ms', elapsed, undefined, 'ms')

await trace('submit order', async (span) => {
  span?.setAttribute('items', cart.length)
  await submitOrder(cart)
})

Cron check-ins and feature flags

Feature flags

import { flags } from '@naijacloud/argus/browser'

if (await flags.isOn('new-checkout', user.id)) {
  showNewCheckout()
}
const theme = await flags.variant('theme', user.id, 'light')

Answers are cached for 30 seconds per user. If Argus can't be reached, or the flag doesn't exist, you get the fallback you passed. Cron check-ins belong to scheduled jobs, so send them from your server: see Node.js.

Release and environment

The browser can't read environment variables, so pass both to init(). Set the release at build time, so source maps can be matched to this build:

main.js

init({
  dsn: 'https://<public key>@argus-in.naijacloud.com/<project id>',
  release: import.meta.env.VITE_RELEASE,
  environment: 'production',
})

The environment is production when you don't set one.

Privacy

On by default:

Clicks record the element, never what was typed.
Values of keys such as password, token, secret, authorization, cookie, bvn and card become [Filtered], at any depth.
Card numbers, bearer tokens and JWTs are filtered inside strings.
Query strings are removed from URLs in breadcrumbs.
The user's IP address is not sent unless you set sendDefaultPii: true.

Pass beforeSend to change an event, or return null to drop it, and beforeBreadcrumb to do the same for breadcrumbs:

beforeSend

init({
  dsn: 'https://<public key>@argus-in.naijacloud.com/<project id>',
  beforeSend: (event) =>
    event.exception?.values.at(-1)?.value.includes('ResizeObserver') ? null : event,
})

Already on Sentry

Keep @sentry/browser (or @sentry/react, @sentry/vue). In your Sentry.init call, change the dsn line:

Sentry.init

dsn: 'https://<public key>@argus-in.naijacloud.com/<project id>',

Source maps

Minified bundles make stack traces hard to read. Upload your build's source maps with the same release you pass to init(), and Argus shows your original files. See Source maps, which includes a GitHub Actions workflow for a Vite app.