NestJS
npx @vigiejs/nestjs init
That is the whole setup. The installer:
- installs
@vigiejs/nestjswith your package manager; - adds
import '@vigiejs/nestjs/register'as the first line ofsrc/main.ts, so traces start before Nest loads; - adds
VigieModule.forRoot()to the imports ofsrc/app.module.ts; - writes
VIGIE_URLandVIGIE_KEYto.env; - 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:
npx @vigiejs/nestjs init --url=https://vigie.acme.dev --key=vk_…
The two lines
import '@vigiejs/nestjs/register'
import { NestFactory } from '@nestjs/core'
import { VigieModule } from '@vigiejs/nestjs'
@Module({ imports: [VigieModule.forRoot()] })
export class AppModule {}
forRoot() needs no options. It reads VIGIE_URL, VIGIE_KEY and NODE_ENV, and the name and version in package.json. It loads .env itself when nothing else has.
What is recorded
Every request becomes one wide event with the route as written in the controller (/orders/:id/checkout), the handler (OrdersController.checkout), status, outcome, duration, the signed-in user's id from req.user, and its trace. A thrown HttpException keeps its status; anything else is a 500 with the error and its stack. A 404 is recorded too.
Add your own fields from anywhere in the request:
import { useLogger } from '@vigiejs/nestjs'
@Post(':id/checkout')
async checkout(@Param('id') id: string) {
const order = await this.orders.checkout(id)
useLogger().set({ order: { id: order.id, total: order.total } })
return order
}
Background jobs
Put @VigieTask on the method that runs a job. On a BullMQ or Bull processor, the job's id, attempt, queue and time waited come from the job itself:
import { skipTask, useLogger, VigieTask } from '@vigiejs/nestjs'
@Processor('emails')
export class EmailsProcessor extends WorkerHost {
@VigieTask('emails.send', { integration: 'postwing' })
async process(job: Job<{ to: string; unsubscribed: boolean }>) {
if (job.data.unsubscribed) return skipTask('UNSUBSCRIBED')
useLogger().set({ email: { template: 'welcome' } })
await this.postwing.send(job.data.to)
}
}
Throwing marks the attempt failed. skipTask(code, why?) and retryTask(code, why?) say why it did not run. It works the same on @Cron, @Interval and @OnEvent handlers. Outside a decorator, use task({ kind: 'reports.nightly' }, async ({ log }) => …).
Traces
@vigiejs/nestjs/register starts the standard OpenTelemetry Node SDK with its auto-instrumentations: HTTP, Express, Fastify, Postgres, MySQL, Redis, gRPC and more. Calls to Vigie itself are left out. Set VIGIE_TRACES_OFF=1 to keep wide events and turn tracing off.
Options
All optional, in VigieModule.forRoot({ … }):
| Option | Default | What it does |
|---|---|---|
url | VIGIE_URL | Where Vigie runs. Empty sends nothing, as in tests. |
key | VIGIE_KEY | The ingest key. A Vigie on your machine needs none. |
service | OTEL_SERVICE_NAME, then the package.json name | How the app appears in Vigie. |
environment | APP_ENV, then NODE_ENV | production, staging or development. |
version | APP_VERSION, then the package.json version | Shown on each event. |
ignorePaths | ['/health'] | Requests to skip. |
secretPaths | [] | Path segments followed by a secret. Masked before anything leaves the app. |
pretty | on outside production | Print each event in the terminal too. |
Requires NestJS 11 or 12 on Express or Fastify, and Node 22.12 or later.