@ksfcore/winston-ksf v2.1.3

@ksfcore/winston-ksf

@ksfcore/winston-ksf provides KSF extensions based on winston to provide KSF-compliant log formats and output.

Provide 4 types of transport objects in@ksfcore/winston-ksf:

• KsfBase: provides base classes that conform to KSF logs
• KsfRotate: provides rolling logs output by size
• KsfDate: provides logs output by date
• TafRemote: output to remote log (ksf.ksflog)

And provide a custom log level:

• KsfConfig: Provides log levels and color values that conform to the KSF framework standard

And related helper methods:

• Formatter: provides content formatting methods that conform to the KSF log format standard
• DateFormat: defines the processing method for time-related log scrolling

Please note: If your service runs on the KSF platform, you should use the @ksfcore/logs module directly, which is more convenient

Installation

npm install @ksfcore/winston-ksf

use

var winston = require('winston');

// Requiring `@ksfcore/winston-ksf` will expose

// transports
// `winston.transport.KsfRotate`
// `winston.transport.KsfDate`

// config
// `winston.config.ksf.levels`
// `winston.config.ksf.colors`
require('@ksfcore/winston-ksf');

Log Format

For transport objects that support formatter,@ksfcore/winston-ksf provides 2 methods to format log content:

• Detailed log: Formatter.Detail (options)
• Simplified log: Formatter.Simple (options)

options:

• separ: the separator between the log content items, default value is |

Detailed logs:

var winston = require ('winston');
var winstonKsf = require ('@ksfcore/winston-ksf');

var logger = new (winston.Logger) ({
  transports: [
    new (winston.transports.Console) ({
    formatter: winstonKsf.Formatter.Detail()
    })]
});

The format of the output log is: date time | PID | log level | file name and line number | content

The file name and line number are optional (see Metadata for details)

Streamlined logs

var winston = require ('winston');
var winstonKsf = require ('@ksfcore/winston-ksf');

var logger = new (winston.Logger) ({
  transports: [
    new (winston.transports.Console) ({
    formatter: winstonKsf.Formatter.Simple()
    })]
});

The format of the output log is: date time | content

KsfConfig

winston.config.ksf provides log levels (levels) and colors (colors) that conform to the Ksf framework standard

The log level of the KSF framework from low to high (and its corresponding color) is:

• info: white
• debug: cyan
• warn: yellow
• error: red
• none: grey

Need to actively introduce when using:

logger.setLevels (winston.config.ksf.levels);
winston.addColors (winston.config.ksf.colors);

KsfBase

This module can be used alone or as a base class for other logging modules.

The module implements similar management methods to existing KSF logs:

• Re-open the log file periodically to get changes to fd. (When the user deletes / moves the current file, the module will automatically create a new file)
• During the file opening process, the generated log will be written to the temporary memory queue, waiting to be written once after the file is opened. (As long as the maximum queue length is not exceeded, all logs are written to the file)
• This module uses the filename options.filename for caching, so using the sameoptions.filename multiple times to instantiate this module will only produce a singleton (share an instance)

Standalone

winston.add (winston.transports.KsfBase, options)

options:

• filename: output file name
• interval: Interval for reopening the log file, The default value is 5000ms
• bufferSize: the maximum length of the temporary queue (unit is bar), default value is 10000
• prefix: prefix of each log content, default value is empty
• formatter: Define the log content formatting method, The default value is Formatter.Detail()

As a base class for other classes

Need to rewrite the following 2 objects:

• KsfBase.prototype.name: Transport module name
• KsfBase.prototype._checkfile (callback): This function will be called when the log file is reopened. After the function is processed, it should call callback ([err]) explicitly

E.g:

var KsfFile = function (options) {
var instance = KsfBase.call (this, options);

// Since the parent class has a cache, it is necessary to determine whether the parent class has a return value. If it exists (hits the cache), it returns directly without further initialization.

if (instance) {
return instance;
}

	//Business code
};
util.inherits (KsfFile, KsfBase);

KsfFile.prototype.name = 'ksfFile';

KsfFile.prototype._checkfile = function (cb) {
	//Business code
	cb();
};

winston.transports.KsfFile = KsfFile;

KsfRotate

This module inherits from KsfBase

Provides rolling log output by file size

When the set maximum size is reached, it will automatically scroll down and create a new log file.

For example, if the app.log file is written to the maximum size, the following process will be performed:

delete app \ _n.log
app \ _n-1.log ===> app \ _n.log
... ...
app \ _1.log ===> app \ _2.log
app.log ===> app \ _1.log
create app.log

  winston.add (winston.transports.KsfRotate, options)

options:

• filename: output file name
• maxFiles: maximum total number of files (ie n in the example), default is 10
• maxSize: maximum file size (unit is bytes), default is 10M
• concatStr: The connector between characters in the log file name, The default value is _
• formatter: Define the log content formatting method, The default value is Formatter.Detail()

KsfRotate.Master

If the business script passes Cluster (multi-process start): Worker only writes the file negatively, and moves the file by the master. To solve the problem of multi-process resource competition.

When the service process (Worker) opens the log file for writing, it sends a message to the main process, as follows:

{
	cmd: 'log: rotate',
	msg: {
		filename: String, // file name
		interval: Number, // how often to open the file
		maxFiles: Number, // Maximum number of files
		maxSize: Number, // Maximum single file size
		concatStr: String // Concatenator between characters in log file name
	}
}

After the master process receives the message, it needs to pass it to the KsfRotate.Master.start method. The complete example is as follows:

worker.on ('message', function (msg) {
if (msg && typeof msg === 'object' && msg.cmd === 'log: rotate') {
var data = msg.msg;
KsfRotate.Master.start (data.filename, data.interval, data.maxFiles, data.maxSize, data.concatStr);
}
});

process.on ('exit', function() {
KsfRotate.Master.close();
});

If the service runs through node-agent (or on the KSF platform, you don't need to configure the platform), no explicit Call this module. Just follow the usual writing console. [Log | info | warn | error] to output the rolling log correctly

DateFormat

Defines the processing method for time-dependent log (KsfDate) scrolling:

• Log by day: LogByDay (interval, pattern)
• interval: 1 Roll a log every other day
• pattern:% Y% m% d year month day (eg: 20150101)
• Log by 1 hour: LogByHour (interval, pattern)
• interval: 1 Roll a log every hour
• pattern:% Y% m% d% H year month day hour (eg: 2015010110)
• Log by 10 minutes: LogByMinute (interval, pattern)
• interval: 10 Roll a log every ten minutes
• pattern:% Y% m% d% H% M year, month, day, hour, minute (eg: 201501011020)
• Custom format log: LogByCustom (pattern)
• pattern: user-defined

Where pattern is the time format in the log file name, seelinux strftime

Examples

Rolling a log every other day

DateFormat.LogByDay
Or
new DateFormat.LogByDay()

Roll a log every 20 minutes

new DateFormat.LogByMinute (20)

Scroll a log every 20 minutes, the time format in the file name is% Y-% m-% d_% H:% M

new DateFormat.LogByMinute (20, '% Y-% m-% d_% H:% M')

KsfDate

This module inherits from KsfBase

Provides logs output by date(year, month, day, hour, minute)

When the set time interval is reached, a new log file is automatically created

The format of the output file name is: filename_% Y |% m |% d |% H |% M .log, such as: app_20141015.log

  winston.add (winston.transports.KsfDate, options)

options:

• filename: output file name
• concatStr: The connector between characters in the log file name, The default value is _
• format: interval for creating a new file, as a DateFormat object, default value is FORMAT.LogByDay
• formatter: defines the log content formatting method. The default value is Formatter.Simple()

For convenience use KsfDate.FORMAT = DateFormat

KsfRemote

Provides the function of remote logging, which will output logs to the ksf.ksflog.LogObj service.

Please note: This is not to send the log as soon as it is received, but to integrate the log and send it regularly.

  var logger = new (winston.Logger) ({
    transports: [
      new (winston.transports.KsfRemote) (options)
    ]
  });

options:

• filename: remote log file name (no need to include date, path and other additional information)
• ksfConfig: ksf configuration file path or configured @ ksf / utils.Config instance
• ksfLogServant: remote log service Servant Obj, read configuration file ksf.application.server.log section by default
• interval: Interval for sending logs, The default value is 500ms
• format: interval for creating a new file, as a DateFormat object, default value is FORMAT.LogByDay
• hasSufix: whether the log file name has a .log suffix, default is true
• hasAppNamePrefix: Whether to allow the framework to add a business-related identifier to the log file name. The default value is true
• concatStr: The connector between user-defined characters and date characters in the log file name. The default value is _
• separ: separator between log content items, default is |
• formatter: Define the log content formatting method, The default value is Formatter.Detail()

Please note: KsfRemote`` options.format cannot be FORMAT.LogByCustom

For convenience, KsfRemote.FORMAT = DateFormat

If the service runs through node-agent (or on the KSF platform), you do not need to configure the options.ksfConfig item

Metadata

By specifying Metadata, two kinds of additional data can be output.

pid

With the pid attribute, you can specify the process id part of the log output entry, which is `process.pid 'by default

Such as:

logger.info ('data', {
	pid: 123456
});

Then output:

2015-01-01 00: 00: 01 |123456 | INFO | data

lineno

With the lineno attribute, you can specify the file name and line number part of the log output entry. The default value is empty (that is, this section is not output).

Such as:

logger.info ('data', {
	lineno: 'app.js: 6'
});

Then output:

2015-01-01 00:00:01|123456|INFO|app.js:6 |data