Skip to content

Latest commit

 

History

History
305 lines (231 loc) · 14.5 KB

api.md

File metadata and controls

305 lines (231 loc) · 14.5 KB

CWLogsWritable ⇐ Writable

Kind: global class
Extends: Writable
Emits: putLogEvents, createLogGroup, createLogStream, stringifyError

new CWLogsWritable(options)

Writable stream for AWS CloudWatch Logs.

Params

  • options object
    • .logGroupName string - AWS CloudWatch LogGroup name. It will be created if it doesn't exist.
    • .logStreamName string - AWS CloudWatch LogStream name. It will be created if it doesn't exist.
    • [.cloudWatchLogsOptions] object = {} - Options passed to AWS.CloudWatchLogs service.
    • [.writeInterval] string | number = "nextTick" - Amount of wait time after a Writable#_write call to allow batching of log events. Must be a positive number or "nextTick". If "nextTick", process.nextTick is used. If a number, setTimeout is used.
    • [.retryableDelay] string | number = 150
    • [.retryableMax] number = 100 - Maximum number of times an AWS error marked as "retryable" will be retried before the error is instead passed to onError.
    • [.maxBatchCount] number = 10000 - Maximum number of log events allowed in a single PutLogEvents API call.
    • [.maxBatchSize] number = 1048576 - Maximum number of bytes allowed in a single PutLogEvents API call.
    • [.ignoreDataAlreadyAcceptedException] boolean = true - Ignore DataAlreadyAcceptedException errors. This will bypass onError. See cwlogs-writable/issues/10.
    • [.retryOnInvalidSequenceToken] boolean = true - Retry on InvalidSequenceTokenException errors. This will bypass onError. See cwlogs-writable/issues/12.
    • [.onError] function - Called when an AWS error is encountered. Overwrites onError method.
    • [.filterWrite] function - Filter writes to CWLogsWritable. Overwrites filterWrite method.
    • [.objectMode] boolean = true - Passed to the Writable constructor. See https://nodejs.org/api/stream.html#stream_object_mode.

Example

var CWLogsWritable = require('cwlogs-writable');
var stream = new CWLogsWritable({
  logGroupName: 'my-log-group',
  logStreamName: 'my-stream',
  cloudWatchLogsOptions: {
    region: 'us-east-1',
    accessKeyId: '{AWS-IAM-USER-ACCESS-KEY-ID}',
    secretAccessKey: '{AWS-SECRET-ACCESS-KEY}'
  }
});

cwLogsWritable.logGroupName : string

AWS CloudWatch LogGroup name. The LogGroup will be created if it doesn't exist. Changes to this property will only take affect for the next PutLogEvents API call.

Kind: instance property of CWLogsWritable

cwLogsWritable.logStreamName : string

AWS CloudWatch LogStream name. The LogStream will be created if it doesn't exist. Changes to this property will only take affect for the next PutLogEvents API call.

Kind: instance property of CWLogsWritable

cwLogsWritable.writeInterval : string | number

Amount of wait time after a Writable#_write call to allow batching of log events. Must be a positive number or "nextTick". If "nextTick", process.nextTick is used. If a number, setTimeout is used.

Kind: instance property of CWLogsWritable
Default: "nextTick"

cwLogsWritable.ignoreDataAlreadyAcceptedException : boolean

Ignore DataAlreadyAcceptedException errors returned by PutLogEvents requests.

This will bypass onError.

See cwlogs-writable/issues/10.

Kind: instance property of CWLogsWritable
Default: true

cwLogsWritable.retryOnInvalidSequenceToken : boolean

Resend log events if PutLogEvents requests return a InvalidSequenceTokenException error.

This will bypass onError.

See cwlogs-writable/issues/12.

Kind: instance property of CWLogsWritable
Default: true

cwLogsWritable.retryableMax : number

Maximum number of times an AWS error marked as "retryable" will be retried before the error is instead passed to onError.

Kind: instance property of CWLogsWritable
Default: 100

cwLogsWritable.retryableDelay : string | number

Kind: instance property of CWLogsWritable
Default: "150"

cwLogsWritable.maxBatchCount : number

Maximum number of log events allowed in a single PutLogEvents API call.

Kind: instance property of CWLogsWritable
Default: 10000

cwLogsWritable.maxBatchSize : number

Maximum number of bytes allowed in a single PutLogEvents API call.

Kind: instance property of CWLogsWritable
Default: 1048576

cwLogsWritable.cloudwatch : CloudWatchLogs

The AWS.CloudWatchLogs instance.

Kind: instance property of CWLogsWritable

cwLogsWritable.getQueueSize() ⇒ number

Get the number of log events queued to be sent to AWS CloudWatch Logs.

Does not include events that are actively being sent.

Kind: instance method of CWLogsWritable

cwLogsWritable.clearQueue() ⇒ Array.<{message:string, timestamp:number}>

Remove all log events that are still queued.

Kind: instance method of CWLogsWritable
Returns: Array.<{message:string, timestamp:number}> - Log events removed from the queue.

cwLogsWritable.onError(err, logEvents, next)

Called when an AWS error is encountered. Do not call directly.

The default behavior of this method is call the next argument with the error as the first argument.

logEvents argument will be either:

  • An array of log event objects (see CWLogsWritable#createLogEvent) if error is from PutLogEvents action.
  • null if error is from any action besides PutLogEvents.

The next argument must be called in one of the following ways:

  • next(err) — If the first argument is an instance of Error, an 'error' event will be emitted on the stream, clearQueue is called, and filterWrite is replaced so no further logging will be processed by the stream. This effectively disables the stream.

  • next() or next(logEvents) — The stream will recover from the error and resume sending logs to AWS CloudWatch Logs. The first argument may optionally be an array of log event objects (i.e. logEvents argument) that will be added to the head of the log events queue.

Kind: instance method of CWLogsWritable
Params

  • err Error - AWS error
  • logEvents null | Array.<{message:string, timestamp:number}>
  • next function

Example

var CWLogsWritable = require('cwlogs-writable');
var stream = new CWLogsWritable({
  logGroupName: 'my-log-group',
  logStreamName: 'my-stream',
  onError: function(err, logEvents, next) {
    if (logEvents) {
      console.error(
        'CWLogsWritable PutLogEvents error',
        err,
        JSON.stringify(logEvents)
      );

      // Resume without adding the log events back to the queue.
      next();
    }
    else {
      // Use built-in behavior of emitting an error,
      // clearing the queue, and ignoring all writes to the stream.
      next(err);
    }
  }
}).on('error', function(err) {
  // Always listen for 'error' events to catch non-AWS errors as well.
  console.error(
    'CWLogsWritable error',
    err
  );
});

cwLogsWritable.filterWrite(rec) ⇒ boolean

Filter writes to CWLogsWritable.

Default behavior is to return true if rec is not null or undefined.

Kind: instance method of CWLogsWritable
Returns: boolean - true to include, and false to exclude.
Params

  • rec string | object - Raw log record passed to Writable#write.

cwLogsWritable.reduceOversizedMessage(logEventMessage) ⇒ * | string

Attempt to reduce the specified message so it fits within the 262118 byte limit enforced by PutLogEvents.

Only called for messages that are over the byte limit.

Use Buffer.byteLength() to accurately measure the message size before returning it.

If the string returned is still over the byte limit, this method will not be called again for the log event.

Kind: instance method of CWLogsWritable
Returns: * | string - - The reduced string, or a non-string (i.e. undefined or null) indicating the message cannot be reduced.
See: {CWLogsWritable#event:oversizeLogEvent}
Params

  • logEventMessage string - Stringified log event.

"putLogEvents" (logEvents)

Fired on successful PutLogEvent API calls.

Kind: event emitted by CWLogsWritable
Params

  • logEvents Array.<{message:string, timestamp:number}>

"createLogGroup"

Fired on successful CreateLogGroup API call.

Kind: event emitted by CWLogsWritable

"createLogStream"

Fired on successful CreateLogStream API call.

Kind: event emitted by CWLogsWritable

"stringifyError" (err, rec)

Fired when an error is thrown while stringifying a log event.

Kind: event emitted by CWLogsWritable
Params

  • err Error
  • rec object | string

"oversizeLogEvent" (logEventMessage)

Fired when a log event message is larger than the 262118 byte limit enforced by PutLogEvents.

Kind: event emitted by CWLogsWritable
Params

  • logEventMessage string - Stringified log event.