Current provides the ability to send data via syslog. We provide 2 ports for doing so:
- 10514: TCP plaintext syslog
- 6514: TCP TLS syslog
We don’t support the standard 514 port because it’s commonly filtered on the internet and we would rather the traffic look more like unique syslog being sent to current rather than site-specific syslog.
Current does not support UDP syslog.
When sending syslog data, the token for the stream that the data should be added to must also be included. There are 3 places to embed the token in each message.
Before the syslog header
This is the simplest when syslog software can easily define a custom format.
Each message should be prefixed by @current:TOKEN.
For example:
@current:acaeada0-a4e3-11e5-ba66-48d705b96401 <174>1 2015-12-17T00:06:26-00:00 somehost Go console - - structured=yes
At the beginning of the message text
Similar to specifying it at the very beginning of the syslog header, this is instead at the beginning of the message text with the same @current:TOKEN format.
For example:
<174>1 2015-12-17T00:06:26-00:00 somehost Go console - - @current:acaeada0-a4e3-11e5-ba66-48d705b96401 structured=yes
Using RFC5424 structured data
RFC5424 provides a section within the message that can be used for specifying structured, key/value data, outside of the actual text message itself.
This mechanism also allows for adding additional tags within the structured data block. Any keys specified inside the structured data block for current are added as tags.
The ID is TOKEN@46001. The @46001 is a IANA assigned identifier for current.sh.
For example:
<14>1 2015-06-12T14:18:21-07:00 somehost Go 1 - [acaeada0-a4e3-11e5-ba66-48d705b96401@46001 environment=“production”] structured=yes
This example would result in a tag of environment with a value of production being assigned to the resulting log entry.
Syslog warning
Syslog is a very simple protocol, which makes it easy to use but that ease comes with some ugly failure situations. Because syslog over TCP does not have the server send back confirmations of messages, it’s possible for messages to be lost without the sender knowing.
This loss of messages can occur due to a crash on the receiver side though that’s the uncommon case. The much more common situation is that due to congestion or general internet conditions, the TCP session is terminated. This can happen due to any number of networking cases between the sender and receiver.
When the TCP session is lost, the sender commonly isn’t aware until its own TCP window is full. That means that every message in that window is likely lost, in addition to any messages stored within the sender’s networking buffers.
We will always support syslog because it is an industry standard but we feel it’s important people understand the ways that syslog can let them down.
Alternatives
Our current tool has a send command that allows you to pipe data to it that will be send to current. This process uses an HTTP based post mechanism known as Logplex (this is the same mechanism Heroku uses (they created it)). You can pipe data to current and the reliability of your data reaching current is generally better than using syslog.