Skip to content

API.md

Latest commit

 

History

History
80 lines (55 loc) · 3.72 KB

API.md

File metadata and controls

80 lines (55 loc) · 3.72 KB

Client

A Client object connects to the reciever and sends messages. The Client will automatically reconnect if the connection fails. Any messages sent while the Client is disconnected will be queued and sent when the connection is re-established.

lumberjack.client(tlsConnectOptions, clientOptions={})

Creates a Client.

tlsConnectOptions is passed directly to tls.connect() to create the TLS connection to the receiver (the logstash server.) At a minimum, you should set host and port.

clientOptions consists of:

  • windowSize - the windowSize to send to the receiver (see caveats section for a discussion about how lumberjack-protocol treats the windowSize.) Defaults to 1000.

  • maxQueueSize - the maximum number of messages to queue while disconnected. If this limit is hit, all messages in the queue will be filtered with allowDrop(data). Only messages which this function returns true for will be removed from the queue. If there are still too many messages in the queue at this point the the oldest messages will be dropped. Defaults to 500.

  • allowDrop(data) - this will be called when deciding which messages to drop. By dropping lower priority messages (info and debug level messages, for example) you can increase the chances of higher priority messages getting through when the Client is having connection issues, or if the receiver goes down for a short period of time. This function is used both to drop messages from the queue while disconnected, and to drop messages if the receiver is taking too long to acknowledge messages.

    Note that this function will be called on all messages in the queue every time the queue grows too large - if this function does not return true for any messages, then it could be called for every message in the queue every time a message is queued.

  • options.reconnect - time, in ms, to wait between reconnect attempts. Defaults to 3 seconds.

  • options.unref - if true, will call unref on the underlying socket. This will allow the program to exit if this is the only active socket in the event system.

Events

Client inherits from EventEmitter, and emits the following:

  • connect when the Client connects to the receiver.

  • disconnect(err) when the client disconnects from the receiver, or when the client fails to connect to the receiver. err will be the error which caused the disconnect, if there is one. The Client will automatically reconnect.

  • dropped(count) if messages are dropped because the receiver is not acknowledging messages fast enough, or because the Client is unable to connect to the receiver and the Client's queue is full.

Methods

Client.writeDataFrame(data)

data here should be a {file, host, line, offset} object, where:

  • host - the hostname of the host that generated the line. Defaults to os.hostname().
  • line - the line from the log file. If you are sending to a logstash receiver, this field is mandatory - logstash will freak out if line is missing.
  • file (optional) - the name of the log file.
  • offset (optional) an integer - the offset of the line in the log file.

Additional field in data will be passed up to the receiver. If you are sending to Logstash, it will add these to the log entry.

Client.close()

Cleanly shut down a Client and prevent it from reconnecting. If there are queued messages, they will be lost.

Client.queueHighWatermark

A readable property which returns the largest size the queue has ever been.