README

What is this repository for?

• Custom Logger with capabilities for integrating with NestJS applications as a Dynamic Module
• Uses Winston under the hood, and implements the NestJS LoggerService interface to allow injection into NestJS projects
• v2.0.0

What to expect

This logger follows loose standards which are ever evolving. For example, only the options directly exposed in the LoggerModuleOptions interface are able to be configured directly. Everything else, including winston transport use, formatting, context, metadata handling, etc. is currently "set in stone". As more functionality is released, we'll outline it below.

Some Notes

• Uses the Console transport
  • This decision was made based on the fact that all busie logs are currently forwarded to datadog
• Log messages (i.e. info.message) use a custom format that capitalizes the Log Level, includes the context if possible, and ends with the message provided as the first argument to the log method.
  • you can expect to see logs in the following formats:
    • <LEVEL> [Context] message (i.e. INFO [AppController] hello world!)
    • <LEVEL> - message (i.e. INFO - hello world!)
• additional arguments to the log method call must be javascript objects, and implement the interface given by LogMetadata iterface
  • the logger determines innerContext automatically, and will match the filename and line of the compiled javascript file that the logger is invoked on.

  interface LogMetadata {
    innerContext?: string;
    event?: { name?: string; outcome?: string };
    [key: string]: any;
  }

• Timestamps are included in log output json
• context is included in log output json
• if service option is provided, it is included in log output json
• the name of this project (@busieinc/logger) is provided as logger.name in output json
• the version of this project (npm package version) is provided as logger.version in output json

Using the logger

Logger Module Options

At this time, possible configuration is limited. The interface extends that which is exposed by winston, but only the below items are able to be configured through this module. We are open to suggestions on desired additions.

interface LoggerModuleOptions {
  // optional. provided level will be `lowercased`. default = info
  // note: this logger uses winston.config.npm.levels, and this cannot be overridden at this time
  level?: 'silly' | 'debug' | 'verbose' | 'http' | 'info' | 'warn' | 'error';

  // optional. Will be included as metadata in log output.
  service?: string;

  // optional
  defaultContext?: string;

  // optional. great for local development. outputs as: `level: message stringifiedRest`
  // i.e. info [context?]: Hello World! {foo: "bar"}
  useSimple?: boolean;
}

Example with NestJS

// app.module.ts
import { LoggerModule } from '@busieinc/logger';
@Module({
  imports: [
    LoggerModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        level: config.get('LOG_LEVEL'),
        service: config.get('LOG_SERVICE_METADATA'),
      }),
    }),
  ],
})
export class AppModule {}

// app.service.ts
import { logger } from '@busieinc/logger';

@Injectable()
export class AppService {
  constructor(@SetLoggerContext(AppService.name) private readonly logger: Logger) {}

  doSomething() {
    this.logger.debug('Do something');
    try {
      throw Error('oh no!');
    } catch (e) {
      this.logger.warn('caught an error');
      this.logger.error(e);
    }
  }
}

// main.ts
import { Logger } from '@busieinc/logger';

const app = await NestFactory.create(ApplicationModule, {
  bufferLogs: true,
});

app.useLogger(await app.resolve(Logger)); // app.resolve is necessary because of the Transient scope of this logger

Optional Middleware Usage

import { LoggerModule, LoggerMiddleware } from '@busieinc/logger';

@Module({})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('*');
  }
}

a-la-carte Usage (without NestJS)

import { createBusieLogger, LoggerMiddleware } from '@busieinc/logger';

const opts = { level: 'debug', service: 'test-service', defaultContext: 'README Context' };
const logger = createBusieLogger(opts);

logger.info('test message', { foo: 'bar' });

// reconfigure the logger with a new context
logger.setContext('New Context');

Optional Middleware Usage

import { createBusieLogger, LoggerMiddleware } from '@busieinc/logger';

// regular express app setup

const opts = { level: 'debug', service: 'test-service', defaultContext: 'HTTP' };
const logger = createBusieLogger(opts);
const middleware = new LoggerMiddleware(logger);
app.use(middleware.use);

Contribution guidelines

• Running tests
• Writing tests
• Code review
• Other guidelines

Who do I talk to?

• Authors: [Charles Fortes [email protected], Brady Perry [email protected]]
• Busie, Inc.