Vigie
Connect an app

Adonis

Send an Adonis app's requests, errors, traces and background tasks to Vigie with one command.
node ace add @vigiejs/adonis

That is the whole setup. The installer:

  • installs the official @adonisjs/otel for traces and points it at Vigie;
  • registers a server middleware that turns every request into one wide event, 404s included;
  • writes VIGIE_URL and VIGIE_KEY to .env and validates them in start/env.ts;
  • with a Vigie on a server, opens a page where someone signed in allows the app, so nobody copies a key;
  • sends one test event, and says so only once Vigie accepted it.

In CI, or anywhere without a browser:

node ace configure @vigiejs/adonis --url=https://vigie.acme.dev --key=vk_…

Add your own fields

Each request's event is ctx.log. Add what matters to you, nested as you like:

start/routes.ts
router.post('/orders', async ({ request, log }) => {
  const order = await Order.create(request.all())
  log.set({ order: { id: order.id, total: order.total } })
  return order
})

The fields show up flattened (order.id, order.total), searchable on Logs, and drawn by your log renderers.

Background tasks

Wrap each attempt of a job in task(). Throwing marks it failed; skip() and retry() say why it did not run:

import { task } from '@vigiejs/adonis'

await task({ kind: 'invoices.sync', id: job.id, attempt: job.attempts, integration: 'invoxa' }, async ({ log, skip }) => {
  if (!account.invoxaId) return skip('NO_INVOXA_ACCOUNT')
  const synced = await invoxa.sync(account)
  log.set({ invoices: { synced } })
})

Anything else, a script or a cron, can be one wide event with runWithWideEvent({ operation: 'reports.nightly' }, async (log) => …).

Config

config/vigie.ts, written by the installer:

OptionWhat it does
urlWhere Vigie runs. Empty sends nothing, as in tests.
keyThe ingest key. A Vigie on your machine needs none.
service, environment, versionHow the app appears in Vigie. Read from APP_NAME, APP_ENV, APP_VERSION.
ignorePathsRequests to skip, such as /health.
secretPathsPath segments followed by a secret, such as webhooks for /webhooks/:token. Masked before anything leaves the app.
prettyPrint each event in the terminal too. On outside production.

If config/otel.ts already existed, the installer leaves it alone and prints the destination to add.

Requires Adonis 6 or 7 and Node 22 or later.

Copyright © 2026