@icd-iot-aicf/nestjs-logger 0.1.6 → 0.1.8

package/README.md

@@ -1,85 +1,248 @@
-<p align="center">
-  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
-</p>
-
-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
-[circleci-url]: https://circleci.com/gh/nestjs/nest
-
-  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
-    <p align="center">
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
-<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
-<a href="https://coveralls.io/github/nestjs/nest?branch=master" target="_blank"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#9" alt="Coverage" /></a>
-<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
-<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
-<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
-  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
-    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
-  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
-</p>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
-
-## Description นะจ้ะ
-
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
-
-## Project setup
+# @icd-iot-aicf/nestjs-logger
 
+NestJS logging and metrics toolkit with opinionated formats (AICF, Cloudron, ESB), Winston-based logger, and Prometheus metrics. Ships with ready-to-use middleware, interceptors, and decorators for structured logs and service KPIs.
+
+- Logger: Winston, JSON payloads, async-context aware
+- Formats: aicf | cloudron | esb
+- Metrics: Prometheus counters/gauges, HTTP middleware, manual API
+- Extras: standard response codes, decorators, guards, utilities
+
+
+## Install
+
+```bash
+npm install @icd-iot-aicf/nestjs-logger
+```
+Or
 ```bash
-$ npm install
+yarn add @icd-iot-aicf/nestjs-logger
 ```
 
-## Compile and run the project
+Requirements:
+- NestJS v11
+- Express platform (default for Nest)
+- Optional: set env C20_NAME to prefix Prometheus metric names
+
+
+## Quick start
+
+1) Configure the library (global) using AppLogConfigModule
+
+```ts
+import { Module, MiddlewareConsumer } from '@nestjs/common';
+import {
+  AppLogConfigModule,
+  LoggerModule,
+  MetricsModule,
+  HTTPLogsMiddleware,
+  HTTPMetricsMiddleware,
+} from '@icd-iot-aicf/nestjs-logger';
+import { FORMAT_TYPE, DEBUG_MODE } from '@icd-iot-aicf/nestjs-logger';
+
+@Module({
+  imports: [
+    AppLogConfigModule.forRoot({
+      appName: 'my-app',
+      componentName: 'http-api',
+      format: FORMAT_TYPE.AICF, // or FORMAT_TYPE.CLOUDRON, FORMAT_TYPE.ESB
+      logLevel: 'info', // 'info' | 'warning' | 'error' | 'debug'
+      debugLib: DEBUG_MODE.DISABLE,
+      // Optional: map result structure if your response is not the default
+      // structureResponse: { resultCode: 'resultCode', httpCode: 'httpCode', resultDescription: 'resultDescription' },
+    }),
+    LoggerModule,
+    MetricsModule.forRoot({ path: '/metrics' }), // optional options
+  ],
+})
+export class AppModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(HTTPLogsMiddleware, HTTPMetricsMiddleware)
+      .forRoutes('*');
+  }
+}
+```
 
-```bash
-# development
-$ npm run start
+2) Register the HTTP interceptor (correlation headers)
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { HttpInterceptor } from '@icd-iot-aicf/nestjs-logger';
 
-# watch mode
-$ npm run start:dev
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalInterceptors(new HttpInterceptor());
+  await app.listen(3000);
+}
+bootstrap();
+```
 
-# production mode
-$ npm run start:prod
+3) Use decorators to name your operations (recommended for better logs/metrics)
+
+```ts
+import { Controller, Get } from '@nestjs/common';
+import { RecordName, CommandInfo } from '@icd-iot-aicf/nestjs-logger';
+
+@Controller('health')
+export class HealthController {
+  @Get()
+  @RecordName('HealthCheck')
+  @CommandInfo({ CommandName: 'HealthCheck', Description: 'API liveness probe' })
+  ping() {
+    return { ok: true };
+  }
+}
 ```
 
-## Run tests
 
-```bash
-# unit tests
-$ npm run test
+## Logger usage
+
+Inject CustomLoggerService and log structured JSON or plain strings. The library will set appropriate level fields for the chosen format.
 
-# e2e tests
-$ npm run test:e2e
+```ts
+import { Injectable } from '@nestjs/common';
+import { CustomLoggerService } from '@icd-iot-aicf/nestjs-logger';
 
-# test coverage
-$ npm run test:cov
+@Injectable()
+export class ExampleService {
+  constructor(private readonly logger: CustomLoggerService) {}
+
+  doWork() {
+    this.logger.log({ message: 'work started' });
+    // ...
+    this.logger.warn({ message: 'slower than expected' });
+    // ...
+    this.logger.error({ message: 'failure' }, 'optional-stack-trace');
+  }
+}
 ```
 
-## Resources
+Notes:
+- log() is info level. Other methods: warn(), debug(), verbose(), error(message, trace?).
+- Prefer structured objects; strings also work but won’t include format extras.
 
-Check out a few resources that may come in handy when working with NestJS:
 
-- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
-- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
-- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
-- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
-- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
-- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
-- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
+## Automatic HTTP logs
 
-## Support
+- HTTPLogsMiddleware emits inbound/outbound logs per request using the configured format (AICF/Cloudron/ESB).
+- Use @RecordName to categorize metrics/logs by endpoint/business name.
+- HttpInterceptor reads correlation headers:
+  - x-ais-orderref: transaction id
+  - x-origin-session: session chain (if present)
 
-Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
 
-## Stay in touch
+## Metrics
 
-- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
-- Website - [https://nestjs.com](https://nestjs.com/)
-- Twitter - [@nestframework](https://twitter.com/nestframework)
+The library exposes a Prometheus endpoint (via @willsoto/nestjs-prometheus) and tracks:
+- request totals by path/method/status
+- time-bucket counters
+- concurrent requests (current and max)
 
-## License
+Setup was done in Quick start. Ensure C20_NAME is set in your environment to prefix metric names.
+
+Manual metrics API:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { MetricsManualService } from '@icd-iot-aicf/nestjs-logger';
+import { RESULTS } from '@icd-iot-aicf/nestjs-logger';
+
+@Injectable()
+export class TaskRunner {
+  constructor(private readonly metrics: MetricsManualService) {}
+
+  async run() {
+    this.metrics.increment();
+    try {
+      // ... your work
+      this.metrics.finish('POST', RESULTS.SUCCESS);
+    } catch (e) {
+      this.metrics.finish('POST', RESULTS.INTERNAL_SERVER_ERROR);
+      throw e;
+    }
+  }
+}
+```
+
+Customize metrics endpoint:
+
+```ts
+MetricsModule.forRoot({ path: '/custom-metrics', defaultMetrics: { enabled: true } });
+```
+
+
+## Decorators for external calls
 
-Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+Tag outbound calls (dependencies) to enrich detail/endpoint logs.
+
+```ts
+import { EXTCMDName, NodeName } from '@icd-iot-aicf/nestjs-logger';
+
+@NodeName('user-service')
+export class UserClient {
+  @EXTCMDName({ cmdName: 'GetUser', action: 'HTTP', subAction: 'GET' })
+  async getUser() {
+    // call your HTTP client here
+  }
+}
+```
+
+
+## Standard responses (helpers)
+
+Use pre-defined operation statuses for consistency.
+
+```ts
+import { RESULTS } from '@icd-iot-aicf/nestjs-logger';
+import { HttpCode } from '@nestjs/common';
+
+// in controller method
+@HttpCode(RESULTS.SUCCESS.httpCode)
+get() {
+  return { ...RESULTS.SUCCESS, data: { ok: true } };
+}
+```
+
+If your response uses different field names, set structureResponse in AppLogConfigModule.forRoot so metrics can extract resultCode/httpCode.
+
+
+## Configuration reference
+
+AppLogConfigModule.forRoot({ ...config })
+- appName: string (required)
+- componentName: string (required)
+- format: FORMAT_TYPE.AICF | FORMAT_TYPE.CLOUDRON | FORMAT_TYPE.ESB (required)
+- logLevel?: 'info' | 'warning' | 'error' | 'debug' (default 'info')
+- debugLib?: DEBUG_MODE (default DISABLE)
+- structureResponse?: { resultCode?: string; httpCode?: string; resultDescription?: string }
+
+Common enums
+```ts
+import { FORMAT_TYPE, DEBUG_MODE } from '@icd-iot-aicf/nestjs-logger';
+```
+
+
+## What’s exported
+
+From the package root:
+- Modules: LoggerModule, MetricsModule, AppLogConfigModule
+- Services: CustomLoggerService, MetricsService, MetricsManualService
+- Middleware: HTTPLogsMiddleware, HTTPMetricsMiddleware
+- Interceptors: HttpInterceptor, CoreLogsInterceptor, AmqpInterceptor
+- Decorators: RecordName, CommandInfo, EXTCMDName, NodeName, RecordManual
+- Config: FORMAT_TYPE, DEBUG_MODE
+- Helpers: RESULTS, STATUS_METHOD, dayJs
+
+
+## Troubleshooting
+- No logs? Ensure AppLogConfigModule.forRoot is imported before LoggerModule and that HTTPLogsMiddleware is applied.
+- Missing correlation? Register HttpInterceptor globally.
+- Metrics labels show undefined path? Use @RecordName; also ensure your controllers are hit after middleware.
+- Metric names start with undefined_: set env C20_NAME in your process.
+- Cloudron/ESB format specifics: pick FORMAT_TYPE matching your deployment pipeline; the library adjusts level fields automatically.
+
+
+## License
+UNLICENSED

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export * from './logger/core/functions/global-function';
 export * from './common/helper/response';
 export * from './logger/core/services/summary-flush.service';
 export * from './logger/core/database/hook-ingress.database';
+export * from './logger/aicf/dtos/aicf.dto';

package/dist/index.js

@@ -35,4 +35,5 @@ __exportStar(require("./logger/core/functions/global-function"), exports);
 __exportStar(require("./common/helper/response"), exports);
 __exportStar(require("./logger/core/services/summary-flush.service"), exports);
 __exportStar(require("./logger/core/database/hook-ingress.database"), exports);
+__exportStar(require("./logger/aicf/dtos/aicf.dto"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAyC;AACzC,4DAA0C;AAC1C,+DAA6C;AAC7C,mEAAiD;AACjD,yDAAuC;AACvC,0DAAwC;AACxC,gDAA8B;AAC9B,iEAA+C;AAC/C,0DAAwC;AACxC,qEAAmD;AACnD,4EAA0D;AAC1D,8DAA4C;AAC5C,wFAAsE;AACtE,0EAAwD;AACxD,yCAAuB;AACvB,wEAAsD;AACtD,0DAAwC;AACxC,0EAAwD;AACxD,2DAAyC;AACzC,+EAA6D;AAC7D,+EAA6D"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAyC;AACzC,4DAA0C;AAC1C,+DAA6C;AAC7C,mEAAiD;AACjD,yDAAuC;AACvC,0DAAwC;AACxC,gDAA8B;AAC9B,iEAA+C;AAC/C,0DAAwC;AACxC,qEAAmD;AACnD,4EAA0D;AAC1D,8DAA4C;AAC5C,wFAAsE;AACtE,0EAAwD;AACxD,yCAAuB;AACvB,wEAAsD;AACtD,0DAAwC;AACxC,0EAAwD;AACxD,2DAAyC;AACzC,+EAA6D;AAC7D,+EAA6D;AAC7D,8DAA4C"}