Skip to content

Latest commit

 

History

History
347 lines (240 loc) · 11.5 KB

tars-winston-tars.md

File metadata and controls

347 lines (240 loc) · 11.5 KB
Raw

@tars/winston-tars

@tars/winston-tars provides TARS extensions based on winston to provide TARS-compliant log formats and output.

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

  • TarsBase: provides base classes that conform to TARS logs
  • TarsRotate: provides rolling logs output by size
  • TarsDate: provides logs output by date
  • TafRemote: output to remote log (tars.tarslog)

And provide a custom log level:

  • TarsConfig: Provides log levels and color values that conform to the TARS framework standard

And related helper methods:

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

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

Installation

npm install @tars/winston-tars

use

var winston = require('winston');

// Requiring `@tars/winston-tars` will expose

// transports
// `winston.transport.TarsRotate`
// `winston.transport.TarsDate`

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

Log Format

For transport objects that support formatter, @tars/winston-tars 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 winstonTars = require ('@tars/winston-tars');

var logger = new (winston.Logger) ({
  transports: [
    new (winston.transports.Console) ({
    formatter: winstonTars.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 winstonTars = require ('@tars/winston-tars');

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

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

TarsConfig

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

The log level of the TARS 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.tars.levels);
winston.addColors (winston.config.tars.colors);

TarsBase

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

The module implements similar management methods to existing TARS 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 same options.filename multiple times to instantiate this module will only produce a singleton (share an instance)

Standalone

winston.add (winston.transports.TarsBase, 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:

  • TarsBase.prototype.name: Transport module name
  • TarsBase.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 TarsFile = function (options) {
var instance = TarsBase.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 (TarsFile, TarsBase);

TarsFile.prototype.name = 'tarsFile';

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

winston.transports.TarsFile = TarsFile;

TarsRotate

This module inherits from TarsBase

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.TarsRotate, 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()

TarsRotate.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 TarsRotate.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;
TarsRotate.Master.start (data.filename, data.interval, data.maxFiles, data.maxSize, data.concatStr);
}
});

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

If the service runs through node-agent (or on the TARS 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 (TarsDate) 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, see linux 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')

TarsDate

This module inherits from TarsBase

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.TarsDate, 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 TarsDate.FORMAT = DateFormat

TarsRemote

Provides the function of remote logging, which will output logs to the tars.tarslog.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.TarsRemote) (options)
    ]
  });

options:

  • filename: remote log file name (no need to include date, path and other additional information)
  • tarsConfig: tars configuration file path or configured @ tars / utils.Config instance
  • tarsLogServant: remote log service Servant Obj, read configuration file tars.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: TarsRemote`` options.format cannot be FORMAT.LogByCustom

For convenience, TarsRemote.FORMAT = DateFormat

If the service runs through node-agent (or on the TARS platform), you do not need to configure the options.tarsConfig 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