![\"log-nest\"](\"assets/log-nest-logo-251x256.png\"){kind=logo}
\n\n \n
/lɒx nɛs/
\n\n[](https://www.npmjs.com/package/@bratislava/log-nest)\n\nShared NestJS logging and error-handling infrastructure. Made to be used by the NestJS applications of the city\nof [Bratislava](https://github.com/bratislava).\n\n## Motivation\n\nOur backends log to [Grafana Loki](https://grafana.com/oss/loki/), and multi-line output (stack traces, pretty-printed\nJSON) breaks up into separate, unrelated log entries there. So the core rule of this package is: **one event = one\nline** of space-separated `key=\"value\"` pairs ([logfmt](https://brandur.org/logfmt)), which Loki parses into queryable\nlabels.\n\nEverything else follows from that:\n\n- `LineLoggerService` formats every log call, including stack traces, as a single logfmt line.\n- `ErrorFactoryService` builds exceptions that carry structured metadata: a machine-readable `errorName` for querying,\n an `alert` flag for Grafana alerting, and log-only context the client must never see.\n- The exception filters and `AppLoggerMiddleware` cooperate to split each error into its two audiences: the sanitized\n JSON response goes to the client, while the full picture (cause chain, `console` context, stack) goes to the log.\n- Code running outside the request-handling chain (cron jobs, startup tasks, event handlers) is covered too: the\n `@HandleErrors` decorator logs errors the exception filters would never see, and registering `LineLoggerService`\n as the NestJS logger keeps the framework's own output logfmt as well.\n\n## Installation\n\n`npm i @bratislava/log-nest`\n\nRequires NestJS 12 and Node 24. The package is ESM-only; CommonJS apps load it through `require(esm)`.\n\n## Using the library\n\n### Quick start\n\nRegister the module once at the app root. `alertReporting` is the app-specific list of error-enum values that should\nraise a Grafana alert when thrown (`ErrorEnum.BAD_GATEWAY_AUTH_ERROR` should always be on it). Keep the list in a\nseparate file, it doubles as the app's single overview of which errors alert:\n\n```ts\n// alert-reporting.ts\nimport {ErrorEnum} from '@bratislava/log-nest'\n\nexport const alertReporting: readonly string[] = [\n ErrorEnum.BAD_GATEWAY_AUTH_ERROR,\n ErrorEnum.DATABASE_ERROR,\n // ...whatever else should page you\n]\n```\n\n```ts\n// app.module.ts\nimport {MiddlewareConsumer, Module, NestModule} from '@nestjs/common'\nimport {\n AppLoggerMiddleware,\n NestLoggingModule,\n LogSanitizationModule,\n} from '@bratislava/log-nest'\n\nimport {alertReporting} from './alert-reporting'\n\n@Module({\n imports: [\n NestLoggingModule.forRoot({alertReporting}),\n LogSanitizationModule.forRoot(), // registers redactors + the allowlist for @LogRedact/@LogAllowList\n ],\n})\nexport class AppModule implements NestModule {\n configure(consumer: MiddlewareConsumer): void {\n consumer.apply(AppLoggerMiddleware).forRoutes('*')\n }\n}\n```\n\n`AppLoggerMiddleware` depends on both `LogRedactionService` and `LogAllowListService`, so\n`LogSanitizationModule.forRoot()` must be imported even if you don't configure any redactors or allowlist yet. Omitting\n`allowShape` denies by default: nothing is logged until an `allowShape` here or a per-route `@LogAllowList` explicitly\nallows it.\n\nThen wire the logger and the global exception filters in `main.ts`:\n\n```ts\n// main.ts\nimport {NestFactory} from '@nestjs/core'\nimport {\n ErrorFilter,\n HttpExceptionFilter,\n LineLoggerService,\n UnknownExceptionFilter,\n} from '@bratislava/log-nest'\n\nconst app = await NestFactory.create(AppModule, {\n logger: new LineLoggerService(),\n})\n// Order matters: later filters take precedence, and HttpException extends\n// Error. Swap ErrorFilter/HttpExceptionFilter and ErrorFilter would swallow\n// HttpExceptions too.\napp.useGlobalFilters(\n new UnknownExceptionFilter(),\n new ErrorFilter(),\n new HttpExceptionFilter(),\n)\nawait app.listen(3000)\n```\n\nThat's the whole setup. See [Motivation](#motivation) for how the pieces cooperate.\n\n### Throwing errors: `ErrorFactoryService`\n\n`NestLoggingModule` provides and globally exports `ErrorFactoryService`, so it can be injected anywhere without\nre-importing. Each factory method takes an `options` object and *returns* an `HttpException`.\n\n```ts\n\n@Injectable()\nexport class FormsService {\n constructor(private readonly errorFactoryService: ErrorFactoryService) {\n }\n\n async getForm(id: string): Promise