Errors with a Sentry SDK

Argus speaks the Sentry protocol. Install the official Sentry SDK for your stack, or keep the one you have, and set its DSN to your Argus DSN.

6 min read

Get a DSN

Open Argus → Sources and connect a source.

A Naijacloud service

Choose A Naijacloud service, pick a web service or cron job, and turn on Send errors to Argus. Then redeploy. Each deploy from then on gets three environment variables:

Variable	Value
`SENTRY_DSN`	The service's Argus DSN
`SENTRY_RELEASE`	The release being deployed, so Argus can tell which deploy an error started in
`SENTRY_ENVIRONMENT`	The environment's name, such as `prod`

Values you set yourself win: a SENTRY_DSN already in the service's environment variables is left alone.

The switch supplies the settings, not the SDK. Your app still needs a Sentry SDK installed and initialised, as below. Static sites and databases don't send errors.

An app hosted anywhere

Choose An app hosted anywhere, give the app a name such as checkout-api, and choose Get my DSN. The DSN looks like this:

DSN format

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

Set it as SENTRY_DSN where the app runs, and set SENTRY_RELEASE to your commit so Argus can say which deploy started an error.

Already on Sentry? Keep your SDK and its setup. Change the DSN to your Argus DSN and redeploy.

Set up the SDK

Each snippet reads the DSN from the environment. Use the official Sentry package for your stack. To send logs, metrics, cron check-ins and flag checks through the same setup, use an Argus SDK instead.

// npm install @sentry/node
// Load this before the rest of your app.
const Sentry = require('@sentry/node');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.SENTRY_RELEASE,
  environment: process.env.SENTRY_ENVIRONMENT || 'production',
});

A DSN's public key is public by design: browser code has to carry it.

Check the connection

After you add a source, Argus waits for its first event and opens it when it arrives. Send a test event checks the connection without touching your code.

If nothing arrives within a few minutes:

Check SENTRY_DSN is set where the app runs, not only on your laptop.
Your server must reach argus-in.naijacloud.com over HTTPS.
Some SDKs only send from production builds. Trigger an error there.
If the test event arrives but yours don't, the SDK isn't starting.

Source maps

Minified JavaScript makes stack traces hard to read: every frame points at line 1 of index-4f2a.js. Upload your build's source maps and Argus shows the original file, line and function instead.

Argus doesn't take source maps from a Naijacloud build by itself yet, so apps hosted on Naijacloud and apps hosted anywhere else upload them the same way: with an upload token, from the step that builds the app.

Create an upload token

An upload token belongs to one source. It can upload source maps and record deploys for that source, and nothing else: it can't read your errors.

For an app hosted anywhere, open Argus → Sources and choose the source. For a Naijacloud service, open the service's Argus tab and choose Errors.
Under Upload tokens, choose Create upload token and give it a name, such as GitHub Actions.
Copy the token. It starts with argus_up_, and you won't see it again. Store it as a secret in your CI, such as ARGUS_UPLOAD_TOKEN.

The list shows each token's first characters and when it was last used. Revoke stops a token at once. Maps it already uploaded stay. A source can have up to 20 tokens.

Upload a map

Send each .map file's JSON as the request body, with two query parameters:

Parameter	Value
`release`	The release your SDK sends, exactly. A map only applies to events from the same release.
`name`	Where the minified file is served, with `~` in place of the scheme and host. `https://shop.ng/assets/app.js` is `~/assets/app.js`.

Upload one source map

bash

curl -X POST "https://argus-api.naijacloud.com/v1/cli/sourcemaps?release=$RELEASE&name=~/assets/index.js" \
  -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @dist/assets/index.js.map

Argus answers 201 with the release, name and size it stored. To upload every map in a build folder, run this from the folder your site is served from (here dist):

Upload every map in dist

bash

cd dist
find . -name '*.js.map' | while read -r map; do
  file="${map#./}"
  curl --fail-with-body -sS -X POST \
    "https://argus-api.naijacloud.com/v1/cli/sourcemaps?release=$RELEASE&name=~/${file%.map}" \
    -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
    --data-binary "@$map" || exit 1
done

Each map can be up to 16 MB, and must be a version 3 source map with one map per minified file. Index maps (with sections) are refused. Uploading the same release and name again replaces the map. A release holds up to 500 maps, a workspace up to 512 MB, and only the 20 newest releases' maps are kept.

Argus applies maps when you open an event, not when it arrives, so a map uploaded after an error still makes that error readable.

GitHub Actions

This workflow builds a Vite app with the commit as its release, uploads the maps, and records the deploy. Add ARGUS_UPLOAD_TOKEN under the repository's Settings → Secrets and variables → Actions first, and have your SDK's release read VITE_RELEASE, as in the Browser snippet above.

.github/workflows/sourcemaps.yml

yaml

name: Build and upload source maps

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      RELEASE: ${{ github.sha }}
      ARGUS_UPLOAD_TOKEN: ${{ secrets.ARGUS_UPLOAD_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      # Vite writes .map files beside the bundles with `build.sourcemap: true`.
      - run: npm run build
        env:
          VITE_RELEASE: ${{ github.sha }}
      - name: Upload source maps to Argus
        working-directory: dist
        run: |
          find . -name '*.js.map' | while read -r map; do
            file="${map#./}"
            curl --fail-with-body -sS -X POST \
              "https://argus-api.naijacloud.com/v1/cli/sourcemaps?release=$RELEASE&name=~/${file%.map}" \
              -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
              --data-binary "@$map" || exit 1
          done
      - name: Record the deploy in Argus
        run: |
          curl --fail-with-body -sS -X POST "https://argus-api.naijacloud.com/v1/cli/deploys" \
            -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"release\": \"$RELEASE\", \"environment\": \"production\", \"commitSha\": \"$GITHUB_SHA\"}"

The deploy request takes release (required), and optionally environment, commitSha and url. Argus uses it to say which deploy an error first appeared in.

If you'd rather not serve the maps to visitors, delete the .map files after the upload step and before you publish the folder.

A command-line tool for these uploads is coming.

How errors become issues

Argus groups events that have the same cause into one issue, using the first rule that applies:

Your own grouping key. An event's fingerprint, if your code sets one.
Exception type and your own stack frames. Module and function names only, without line numbers, so a deploy that moves code doesn't split an issue.
The message, with variables blanked. Numbers, IDs, emails and quoted strings are ignored, so "user 4812 not found" and "user 77 not found" are one issue.

Resolve, ignore or assign an issue from its page. A resolved issue that gets a new event is unresolved again and marked as came back.

Error emails

Argus emails your workspace's alert recipients when:

an issue is new,
a resolved issue comes back, or
an issue spikes well above its usual hourly rate.

You get at most one email per issue per hour.

Monthly allowance

Each plan includes a number of errors a month, shown under Argus → Usage & plan. Argus emails the alert recipients at 80% and again at 100%. Past the allowance, new events are refused with 429 until the next month. Your app keeps running: Sentry SDKs drop the event and back off for the time the response asks. Your plan's allowance is under Argus → Usage & plan.