@nfjs/logger

Русский

Единый слой абстракций логирования для nfjs.

Что делает модуль

• предоставляет singleton API getLogger(name) (без доступа через container);
• по умолчанию пишет в console backend в стабильном JSON (1 событие = 1 строка);
• применяет статическую политику логирования по namespace:
  • включение/выключение;
  • уровни;
  • наследование по префиксу (project.main.auth наследует project.main).
• поддерживает child-контекст;
• поддерживает interceptor pipeline:
  • глобальные interceptor'ы (для всех логгеров),
  • scoped interceptor'ы (по имени/префиксу логгера);
• поддерживает redaction секретов;
• сериализует Error (name/message/stack/cause/code + дополнительные поля);
• пишет warn/error/fatal в stderr, остальное в stdout.

Конфигурация (config.json)

{
  "@nfjs/logger": {
    "console": {
      "base": {
        "service": "nfjs-demo",
        "env": "local"
      },
      "redact": {
        "paths": [
          "*.password",
          "*.token",
          "*.access_token",
          "*.refresh_token",
          "*.client_secret"
        ],
        "censor": "[REDACTED]",
        "remove": false
      },
      "maxDepth": 8,
      "includeStack": true,
      "messageKey": "msg",
      "loggerKey": "logger_name",
      "timeKey": "time",
      "levelKey": "level",
      "stderrLevels": ["warn", "error", "fatal"]
    },
    "policy": {
      "default": {
        "enabled": true,
        "level": "info"
      },
      "rules": {
        "project.main": {
          "enabled": true,
          "level": "debug"
        },
        "project.main.auth": {
          "enabled": true,
          "level": "trace"
        },
        "mdm.import": {
          "enabled": false
        }
      }
    }
  }
}

Формат события (по умолчанию)

{
  "time": 1772672801000,
  "level": "info",
  "logger_name": "project.main",
  "service": "nfjs-demo",
  "env": "local",
  "msg": "init started",
  "module": "project/main"
}

Использование

import { getLogger, addGlobalLoggerInterceptor } from '@nfjs/logger';

const logger = getLogger('project.main', {
  beforeWrite(ctx) {
    return {
      meta: {
        ...(ctx.meta || {}),
        source: 'main'
      }
    };
  }
});
logger.info('init started');

const authLogger = logger.scope('auth').child({ module: 'project/main' });
authLogger.debug('token exchange');

addGlobalLoggerInterceptor({
  name: 'global-extra',
  beforeWrite(ctx) {
    return {
      meta: {
        ...(ctx.meta || {}),
        app_part: 'backend'
      }
    };
  }
});

Backend-провайдеры

Модуль поддерживает переключение backend через экземпляр Loggers внутри @nfjs/logger.

English

Unified logging abstraction layer for nfjs.

What this module does

• exposes singleton API getLogger(name) (no container access);
• uses console backend by default with stable JSON output (1 event = 1 line);
• applies static namespace policy:
  • enable/disable;
  • level filtering;
  • prefix inheritance (project.main.auth inherits project.main).
• supports child context;
• supports interceptor pipeline:
  • global interceptors (for all loggers),
  • scoped interceptors (by logger name/prefix);
• supports secret redaction;
• serializes Error consistently (name/message/stack/cause/code + extra fields);
• writes warn/error/fatal to stderr, other levels to stdout.

Configuration (config.json)

{
  "@nfjs/logger": {
    "console": {
      "base": {
        "service": "nfjs-demo",
        "env": "local"
      },
      "redact": {
        "paths": [
          "*.password",
          "*.token",
          "*.access_token",
          "*.refresh_token",
          "*.client_secret"
        ],
        "censor": "[REDACTED]",
        "remove": false
      },
      "maxDepth": 8,
      "includeStack": true,
      "messageKey": "msg",
      "loggerKey": "logger_name",
      "timeKey": "time",
      "levelKey": "level",
      "stderrLevels": ["warn", "error", "fatal"]
    },
    "policy": {
      "default": {
        "enabled": true,
        "level": "info"
      },
      "rules": {
        "project.main": {
          "enabled": true,
          "level": "debug"
        },
        "project.main.auth": {
          "enabled": true,
          "level": "trace"
        },
        "mdm.import": {
          "enabled": false
        }
      }
    }
  }
}

Event format (default)

{
  "time": 1772672801000,
  "level": "info",
  "logger_name": "project.main",
  "service": "nfjs-demo",
  "env": "local",
  "msg": "init started",
  "module": "project/main"
}

Usage

import { getLogger, addGlobalLoggerInterceptor } from '@nfjs/logger';

const logger = getLogger('project.main', {
  beforeWrite(ctx) {
    return {
      meta: {
        ...(ctx.meta || {}),
        source: 'main'
      }
    };
  }
});
logger.info('init started');

const authLogger = logger.scope('auth').child({ module: 'project/main' });
authLogger.debug('token exchange');

addGlobalLoggerInterceptor({
  name: 'global-extra',
  beforeWrite(ctx) {
    return {
      meta: {
        ...(ctx.meta || {}),
        app_part: 'backend'
      }
    };
  }
});

Backend providers

Backend can be switched through the internal Loggers instance in @nfjs/logger.