lumberjack-protocol
Version:
Node.js implementation of the lumberjack protocol.
81 lines (55 loc) • 3.81 kB
Markdown
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.
Creates a Client.
`tlsConnectOptions` is passed directly to
[`tls.connect()`](http://nodejs.org/api/tls.html#tls_tls_connect_options_callback) 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](https://github.com/benbria/node-lumberjack-protocol#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](https://nodejs.org/api/net.html#net_socket_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](http://nodejs.org/api/events.html#events_class_events_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.
Cleanly shut down a Client and prevent it from reconnecting. If there are queued messages, they
will be lost.
A readable property which returns the largest size the queue has ever been.