Vigie
Connect an app

NestJS

Send a NestJS app's requests, errors, traces and background jobs to Vigie with one command.
npx @vigiejs/nestjs init

That is the whole setup. The installer:

  • installs @vigiejs/nestjs with your package manager;
  • adds import '@vigiejs/nestjs/register' as the first line of src/main.ts, so traces start before Nest loads;
  • adds VigieModule.forRoot() to the imports of src/app.module.ts;
  • writes VIGIE_URL and VIGIE_KEY to .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

src/main.ts
import '@vigiejs/nestjs/register'
import { NestFactory } from '@nestjs/core'
src/app.module.ts
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({ … }):

OptionDefaultWhat it does
urlVIGIE_URLWhere Vigie runs. Empty sends nothing, as in tests.
keyVIGIE_KEYThe ingest key. A Vigie on your machine needs none.
serviceOTEL_SERVICE_NAME, then the package.json nameHow the app appears in Vigie.
environmentAPP_ENV, then NODE_ENVproduction, staging or development.
versionAPP_VERSION, then the package.json versionShown on each event.
ignorePaths['/health']Requests to skip.
secretPaths[]Path segments followed by a secret. Masked before anything leaves the app.
prettyon outside productionPrint each event in the terminal too.

Requires NestJS 11 or 12 on Express or Fastify, and Node 22.12 or later.

Copyright © 2026