# Setup Error Tracking (Sentry SDK) di NestJS Dokumentasi ini buat masang error tracking (capture exception, request context, stack trace) ke instance Sentry-compatible (GlitchTip self-hosted atau Sentry Cloud) di aplikasi NestJS. ## 1. Prasyarat - Sudah punya DSN dari project di dashboard GlitchTip/Sentry (format: `https://<key>@<domain>/<project_id>`) - Project NestJS pakai `.env` buat konfigurasi ## 2. Instalasi ```bash npm install @sentry/nestjs --save ``` ## 3. Environment variable Tambahin di `.env`: ``` SENTRY_DSN="https://<key>@<domain>/<project_id>" ``` ## 4. Buat file `src/instrument.ts` File ini **harus terpisah** dari `main.ts`, dan berisi `Sentry.init()`. ```ts import 'dotenv/config'; // wajib, load .env sebelum Sentry.init() dipanggil import * as Sentry from '@sentry/nestjs'; Sentry.init({ dsn: process.env.SENTRY_DSN, sendDefaultPii: true, // biar IP, headers, user info ikut kecapture environment: process.env.NODE_ENV || 'production', // Konfigurasi eksplisit biar request body & query params PASTI kecapture // (default behaviour beda-beda antar versi SDK, jadi jangan andelin default) integrations: (defaultIntegrations) => [ ...defaultIntegrations.filter((i) => i.name !== 'RequestData'), Sentry.requestDataIntegration({ include: { ip: true, data: true, // request body query_string: true, // query params headers: true, cookies: true, user: true, }, }), ], }); ``` > Kenapa perlu `dotenv/config` manual: `instrument.ts` diimport paling awal, > sebelum NestJS `ConfigModule` sempat jalan dan load `.env`. Tanpa ini, > `process.env.SENTRY_DSN` masih `undefined` pas `Sentry.init()` dipanggil, > dan SDK diam-diam gak akan pernah ngirim event (cuma warning > "No DSN provided" di log kalau `debug: true`). ## 5. Import di baris paling atas `main.ts` ```ts import './instrument'; // HARUS baris pertama, sebelum import apapun lain import { NestFactory } from '@nestjs/core'; // ...import lain seperti biasa ``` Penting: - **Tanpa** ekstensi `.ts` di akhir (`'./instrument'`, bukan `'./instrument.ts'`) - File-nya harus ada di `src/` (folder yang sama dengan `main.ts`) ## 6. Register `SentryModule` & exception filter global di `app.module.ts` ```ts import { APP_FILTER } from '@nestjs/core'; import { SentryModule, SentryGlobalFilter } from '@sentry/nestjs/setup'; @Module({ imports: [ SentryModule.forRoot(), // HARUS import PERTAMA di array imports // ...module lain ], providers: [ { provide: APP_FILTER, useClass: SentryGlobalFilter }, // HARUS provider PERTAMA // ...provider lain ], }) export class AppModule {} ``` ## 7. Kalau project sudah punya custom exception filter Ini kasus yang sering kelewat. `SentryGlobalFilter` cuma nangkep exception yang **gak** ketangkep filter lain duluan. Kalau ada filter spesifik seperti: ```ts @Catch(PrismaClientKnownRequestError) export class SomeCustomFilter implements ExceptionFilter { ... } ``` ...exception yang match `@Catch(...)` itu **tidak akan pernah** sampai ke `SentryGlobalFilter`, walaupun `SentryModule` sudah ke-setup benar. Solusinya: tambahin `Sentry.captureException(exception)` manual di filter itu. Aturan yang dipakai: **status 5xx / error tak terduga → capture. Status 4xx yang memang disengaja (validasi, not found, unauthorized) → boleh skip**, karena itu flow normal, bukan bug. Helper biar konsisten di semua filter: ```ts // src/common/sentry-report.util.ts import * as Sentry from '@sentry/nestjs'; export function reportIfUnexpected(exception: unknown, httpStatus: number) { if (httpStatus >= 500) { Sentry.captureException(exception); } } ``` Panggil di ujung `catch()` tiap custom filter: ```ts reportIfUnexpected(exception, status); ``` **Checklist:** cari semua custom filter di project sebelum anggap setup selesai: ```bash grep -rln "@Catch(" src/ --include="*.ts" | grep -v node_modules ``` ## 8. Scrub data sensitif (opsional tapi disarankan) Karena `sendDefaultPii: true` bikin request body ikut terkirim penuh, tambahin `beforeSend` di `instrument.ts` buat mask field sensitif: ```ts Sentry.init({ // ...config di atas beforeSend(event) { const sensitiveFields = ['password', 'token', 'secret']; if (event.request?.data) { for (const field of sensitiveFields) { if (event.request.data[field]) event.request.data[field] = '[FILTERED]'; } } return event; }, }); ``` ## 9. Testing Penting: `SentryGlobalFilter` **tidak** mengirim `HttpException` bawaan NestJS (`NotFoundException`, `BadRequestException`, dll) secara default — itu dianggap flow kontrol normal, bukan bug. Buat testing, trigger error yang beneran unhandled, misal lewat constraint DB (contoh Prisma `create()` dengan data yang melanggar unique constraint), bukan `throw new HttpException(...)`. Cara cepat verifikasi: 1. Trigger error via endpoint yang ada request body/query params 2. Cek dashboard → tab **Issues** → buka issue-nya 3. Pastikan section **Request** ada: Body, Query String, Headers, IP ## 10. Troubleshooting | Gejala | Kemungkinan penyebab | |---|---| | `Cannot find module './instrument.ts'` | Ada `.ts` literal di baris import `main.ts`, atau `dist/` lama ke-cache — hapus `dist` dan build ulang | | `Cannot find module './instrument'` padahal sudah tanpa `.ts` | File `instrument.ts` gak ada di `src/`, atau salah folder | | `No DSN provided, client will not send events` (pakai `debug: true`) | `.env` belum ke-load pas `Sentry.init()` jalan — tambahin `import 'dotenv/config'` di baris pertama `instrument.ts` | | Event gak muncul di dashboard padahal `Sentry Logger` bilang "Captured error event" | Cek log container GlitchTip (`docker compose logs glitchtip-web`) barengan waktu trigger — kalau gak ada request masuk sama sekali, cek konektivitas network / DSN salah domain | | Request body / query params kosong di dashboard | Konfigurasi `requestDataIntegration` secara eksplisit (lihat bagian 4), jangan andelin default SDK | | Error yang "seharusnya" muncul tapi gak ada | Kemungkinan ketangkep custom exception filter duluan — lihat bagian 7 | ## Referensi - Dokumentasi resmi Sentry untuk NestJS: https://docs.sentry.io/platforms/javascript/guides/nestjs/