title: Logger

There is no doubt that logs are important part for monitoring application and debugging in Web development.

Built-in enterprise scaled logger, egg-logger, makes developer implement logging more easily than ever before.

Core features:

• Levels
• Universal logging, .error() will save ERROR level logs into a file for later debugging
• Logs from dispatch and runtime are separated
• Create your logger
• Multi-process logs
• Automatic sharding
• High Performance

Location

• Log files are located in ${appInfo.root}/logs/${appInfo.name} by default. For instance, /home/admin/logs/example-app.
• To avoid conflicts between environments and provide a more convenience way to manage logs, log files will be written into logs directory. For instance, /path/to/example-app/logs/example-app.

Change dir in logger:

// config/config.${env}.js
exports.logger = {
  dir: '/path/to/your/custom/log/dir',
};

Type of Logs

Egg offers a few loggers for different scenarios:

• appLogger ${appInfo.name}-web.log，for example example-app-web.log stores logs from application, it will be used in general.
• coreLogger egg-web.log, logs from Egg’s core and plugin.
• errorLogger common-error.log should not be invoked directly. However, .error() in every logger will redirect logs to it for debugging.
• agentLogger egg-agent.log, logs from agent process.

If you want to change names of above loggers, you can override them in config:

// config/config.${env}.js
module.exports = appInfo => {
  return {
    logger: {
      appLogName: `${appInfo.name}-web.log`,
      coreLogName: 'egg-web.log',
      agentLogName: 'egg-agent.log',
      errorLogName: 'common-error.log',
    },
  };
};

Printing

Context Logger

It’s proper to log details in requests with context logger. The logger will append basics about requests to each log. For example, [$userId/$ip/$traceId/${cost}ms $method $url].

ctx.logger.debug('debug info');
ctx.logger.info('some request data: %j', ctx.request.body);
ctx.logger.warn('WARNING!!!!');
// .error will save information in call stack into errorLog file.
// Exceptions must be guaranteed to be Error or object extended from Error, which offers a trace of what functions were called.
ctx.logger.error(new Error('whoops'));

For developers who create frameworks or plugins, ctx.coreLogger is another option in Context Logger.

ctx.coreLogger.info('info');

App Logger

For developers who want to know more details about dispatch in Egg, they can easily use App Logger to make that happen:

// app.js
module.exports = app => {
  app.logger.debug('debug info');
  app.logger.info('Latency: %d ms', Date.now() - start);
  app.logger.warn('warning!');
  app.logger.error(someErrorObj);
};

app.coreLogger in app is similar to ctx.coreLogger in context:

// app.js
module.exports = app => {
  app.coreLogger.info('Latency: %d ms', Date.now() - start);
};

Agent Logger

Agent also supports agent.coreLogger as the same feature to context and app above.

// agent.js
module.exports = agent => {
  agent.logger.debug('debug info');
  agent.logger.info('Latency: %d ms', Date.now() - start);
  agent.logger.warn('warning!');
  agent.logger.error(someErrorObj);
};

For more about Agent, you can take a look at Multi-process.

Encoding

The default encoding setting(utf-8) can be changed via encoding in config:

// config/config.${env}.js
exports.logger = {
  encoding: 'gbk',
};

Log Level

Logs are designed in 5 levels, including NONE, DEBUG, INFO, WARN and ERROR. For inspecting in development, they will also be written into files and printed into terminal as well.

Levels

Generally, Egg will only write logs in levels higher than INFO, so it means that NONE and DEBUG information will be lost in files.

If you want to change the level of the logger, you can make it as follow:

// config/config.${env}.js
exports.logger = {
  level: 'DEBUG', // logs in all level will be written into files
};

Stop writing logs in all levels:

// config/config.${env}.js
exports.logger = {
  level: 'NONE',
};

DEBUG Log in Prodction Environment

To avoid some plugin’s DEBUG logs printing in the production environment causing performance problems, the production environment prohibits printing DEBUG-level logs by default. If there is a need to print DEBUG logs for debugging in the production environment, you need to set allowDebugAtProd configuration to ture.

// config/config.prod.js
exports.logger = {
  level: 'DEBUG',
  allowDebugAtProd: true,
};

In terminal

By default, Egg will only print out INFO, WARN and ERROR in terminal. logger.consoleLevel(default: INFO) is defined as the logger level in terminal. Similarly, it can be changed as following:

Print logs in all levels:

// config/config.${env}.js
exports.logger = {
  consoleLevel: 'DEBUG',
};

Stop printing logs in all levels:

// config/config.${env}.js
exports.logger = {
  consoleLevel: 'NONE',
};

Create your logger

Customized

For common scenarios, it’s unnecessary to create new logger, because too many loggers will make them hard to be managed for later debugging.

The logger you create can be declared in config:

// config/config.${env}.js
const path = require('path');
module.exports = appInfo => {
  return {
    customLogger: {
      xxLogger: {
        file: path.join(appInfo.root, 'logs/xx.log'),
      },
    },
  };
};

Now, you can get loggers via app.getLogger('xxLogger') or ctx.getLogger('xxLogger'), and the logs printed from those loggers are similar to the ones from coreLogger.

Advanced

Logs will be written into files by default. Further, they will also be printed into terminal in development. But what if we need to print those into another place? Creating customized transport can take you there.

Transport can be considered as a tunnel to transfer data in Egg. A logger contains multiple transports, for example the one by default contains fileTransport and consoleTransport.

For concrete scenario, we take common-error.log as an example, which not only printed into files, but also sent to another remote service. At first, we can create a new transport for sending logs to remote:

const co = require('co');
const util = require('util');
const Transport = require('egg-logger').Transport;
class RemoteErrorTransport extends Transport {
  // Create log() to upload logs
  log(level, args) {
    let log;
    if (args[0] instanceof Error) {
      const err = args[0];
      log = util.format('%s: %s\n%s\npid: %s\n', err.name, err.message, err.stack, process.pid);
    } else {
      log = util.format(...args);
    }
    this.options.app.curl('http://url/to/remote/error/log/service/logs', {
      data: log,
      method: 'POST',
    }).catch(console.error);
  }
}
// Transport attached to errorLogger in app.js, makes logs sync to it once those are created.
app.getLogger('errorLogger').set('remote', new RemoteErrorTransport({ level: 'ERROR', app }));

Performance is what we always consider as important part in our services so that logs will firstly be written into memory and transferred to remote later.

Log Sharding

One common requirement you can find in enterprise logs is automatic log sharding, which offers a convenient way for management. Luckily, Egg takes egg-logrotator as built-in solution to meet the need.

Daily Sharding

This is the default way in Egg to cut the logs into files named by .log.YYYY-MM-DD at every 00:00. For example, example-app-web.log will be cut into files as follow, example-app-web.log.YYYY-MM-DD.

Size Sharding

The log file also can be cut into ones by size. For example, Egg will process egg-web.log when its size reach 2G:

// config/config.${env}.js
const path = require('path');
module.exports = appInfo => {
  return {
    logrotator: {
      filesRotateBySize: [
        path.join(appInfo.root, 'logs', appInfo.name, 'egg-web.log'),
      ],
      maxFileSize: 2 * 1024 * 1024 * 1024,
    },
  };
};

Logs written into filesRotateBySize file will never be processed again by date.

Hourly Sharding

There is another option that the log files can be divided into small ones by hour.

For example, we need to cut common-error.log by hour just like following implementation.

// config/config.${env}.js
const path = require('path');
module.exports = appInfo => {
  return {
    logrotator: {
      filesRotateByHour: [
        path.join(appInfo.root, 'logs', appInfo.name, 'common-error.log'),
      ],
    },
  };
};

Logs written into filesRotateByHour file will never be processed again by date.

Performance

Generally, requests are frequent events to Web services, so writing logs into disk after each event will cause more unexpected I/O. Egg takes following strategy to write logs:

Logs will be firstly transferred into memory, and then Egg will asynchronously write them into files by second.

More about egg-logger and egg-logrotator。