@icd-iot-aicf/nestjs-logger

A structured logging and metrics library for NestJS microservices in the ICD IoT platform. It provides automatic request/response logging with team-standard format patterns and a fluent manual logging API — all wired in with a single module import.

Key Features

• Three log format strategies — switch between AICF, Cloudron, and ESB output shapes via config; each format is fully consistent across all log events.
• Automatic HTTP & AMQP logging — middleware and interceptors capture inbound/outbound requests, correlation IDs, and timing with microsecond precision out of the box.
• AsyncLocalStorage context propagation — per-request transaction info, endpoint summaries, and external call metadata flow through the call stack with zero manual threading.
• Prometheus metrics — built-in HTTP counters and gauges via MetricsModule; extend with MetricsManualService for custom business metrics.
• Manual logging API — CustomLoggerService exposes log(), warn(), error(), debug(), and verbose() with typed action DTOs (HttpAction, DBAction, RabbitMQAction, and more).

Installation

npm install @icd-iot-aicf/nestjs-logger

Peer dependencies — ensure your project has these installed:

npm install @nestjs/common @nestjs/core reflect-metadata

Quick Start

// app.module.ts
import { Module } from '@nestjs/common';
import { AppLogConfigModule, FORMAT_TYPE } from '@icd-iot-aicf/nestjs-logger';

@Module({
  imports: [
    AppLogConfigModule.forRoot({
      format: FORMAT_TYPE.AICF,
      appName: 'my-service',
      componentName: 'api',
    }),
  ],
})
export class AppModule {}

// my.service.ts
import { Injectable } from '@nestjs/common';
import { CustomLoggerService, HttpAction, RESULTS } from '@icd-iot-aicf/nestjs-logger';

@Injectable()
export class MyService {
  constructor(private readonly logger: CustomLoggerService) {}

  async getUser(id: string) {
    this.logger.log('Fetching user', HttpAction.GET({ userId: id }));

    // ... business logic ...

    this.logger.log('User fetched', HttpAction.GET({ result: RESULTS.SUCCESS }));
  }
}

Configuration

| Option | Type | Description | |---|---|---| | format | FORMAT_TYPE | Log output shape: AICF | Cloudron | ESB | | appName | string | Application name written into every log entry | | componentName | string | Sub-component or service layer identifier | | debugMode | DEBUG_MODE | Controls verbosity; defaults to OFF |

Automatic Logging

Register the middleware and interceptors in your module to get zero-config HTTP logging:

// app.module.ts
import {
  MiddlewareConsumer,
  Module,
  NestModule,
} from '@nestjs/common';
import {
  AppLogConfigModule,
  HTTPLogsMiddleware,
  FORMAT_TYPE,
} from '@icd-iot-aicf/nestjs-logger';

@Module({
  imports: [
    AppLogConfigModule.forRoot({ format: FORMAT_TYPE.AICF, appName: 'my-service', componentName: 'api' }),
  ],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(HTTPLogsMiddleware).forRoutes('*');
  }
}

Every inbound request will automatically emit structured logs for:

• Inbound / outbound HTTP with correlation headers (x-ais-orderref, x-origin-session)
• Timing in microseconds
• Endpoint-level summary flush on response

Prometheus Metrics

import { MetricsModule } from '@icd-iot-aicf/nestjs-logger';

MetricsModule.forRoot({ path: '/metrics', defaultMetrics: true })

Custom metrics via MetricsManualService:

this.metrics.increment('orders_created_total', { status: 'success' });

Log Action Types

| Class | Methods | |---|---| | HttpAction | .GET() .POST() .PUT() .PATCH() .DELETE() | | DBAction | .CREATE() .READ() .UPDATE() .REMOVE() | | RabbitMQAction | .PRODUCE() .CONSUME() | | KafkaAction | .PRODUCE() .CONSUME() | | LogicAction | .FUNCTION() .CHECKPOINT() | | ExceptionAction | .LOG() |

For a full field-level reference of every key emitted in each log format (AICF, Cloudron), see docs/FORMAT_REFERENCE.md.

Upgrading to v4

Before upgrading, capture a snapshot of your current v3 log output so you can detect any unintended format changes after the upgrade.

Step 1 — While still on v3, copy and run the baseline script:

cp node_modules/@icd-iot-aicf/nestjs-logger/migration/log-snapshot-v3.e2e-spec.ts \
   test/log-snapshot.e2e-spec.ts

npx jest --config ./test/jest-e2e.json --testPathPatterns=log-snapshot --updateSnapshot

git add test/__snapshots__/log-snapshot.e2e-spec.ts.snap
git commit -m "test: capture v3 log format baseline snapshot"

Step 2 — Upgrade the package and apply breaking changes (see v3-to-v4-migration.md in the repo).

Step 3 — Compare v4 output against your baseline:

npx jest --config ./test/jest-e2e.json --testPathPatterns=log-snapshot

Any format differences are shown as a Jest diff. If they are expected (renamed fields from the breaking-changes table), accept them with --updateSnapshot.

The migration guide (v3-to-v4-migration.md) in the library repo contains the full step-by-step breakdown including a list of all breaking changes and renamed fields.

Benchmarks

Performance benchmarks coming soon.

Planned metrics: log throughput (events/sec), middleware overhead (ms/req), memory footprint under load.

License

MIT © ICD IoT Platform Team