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/otelfor traces and points it at Vigie; - registers a server middleware that turns every request into one wide event, 404s included;
- writes
VIGIE_URLandVIGIE_KEYto.envand validates them instart/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:
| Option | What it does |
|---|---|
url | Where Vigie runs. Empty sends nothing, as in tests. |
key | The ingest key. A Vigie on your machine needs none. |
service, environment, version | How the app appears in Vigie. Read from APP_NAME, APP_ENV, APP_VERSION. |
ignorePaths | Requests to skip, such as /health. |
secretPaths | Path segments followed by a secret, such as webhooks for /webhooks/:token. Masked before anything leaves the app. |
pretty | Print 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.