Class SyslogHandler

All Implemented Interfaces:
Closeable, Flushable, AutoCloseable, FlushableCloseable, Protectable

public class SyslogHandler extends ExtHandler
A syslog handler for logging to syslogd.

This handler can write to syslog servers that accept the RFC3164 and RFC5424 formats. Writes can be done via TCP, SSL over TCP or UDP protocols. You can also override the output stream if a custom protocol is needed.

 
Configuration Properties:
Property Description Type Default
serverHostname The address of the syslog server String localhost
port The port of the syslog server int 514
facility The facility used to calculate the priority of the log message Facility USER_LEVEL
appName The name of the application that is logging String java
hostname The name of the host the messages are being sent from. See setHostname(String) for more details String null
syslogType The type of the syslog used to format the message SyslogType RFC5424
protocol The protocol to send the message over Protocol UDP
delimiter The delimiter to use at the end of the message if useDelimiter is set to true String For UDP null - For TCP or SSL_TCP \n
useDelimiter Whether or not the message should be appended with a delimiter boolean For UDP false - For TCP or SSL_TCP true
useCountingFraming Prefixes the size of the message, mainly used for TCP or SSL_TCP, connections to the message being sent to the syslog server. See http://tools.ietf.org/html/rfc6587 for more details on framing types. boolean false
truncate Whether or not a message, including the header, should truncate the message if the length in bytes is greater than the maximum length. If set to false messages will be split and sent with the same header values. boolean true
maxLength The maximum length a log message, including the header, is allowed to be. int For RFC3164 1024 (1k) - For RFC5424 2048 (2k)

  • Field Details

    • DEFAULT_ADDRESS

      public static final InetAddress DEFAULT_ADDRESS
    • DEFAULT_PORT

      public static final int DEFAULT_PORT
      See Also:
    • DEFAULT_SECURE_PORT

      public static final int DEFAULT_SECURE_PORT
      See Also:
    • DEFAULT_ENCODING

      public static final String DEFAULT_ENCODING
      See Also:
    • DEFAULT_FACILITY

      public static final SyslogHandler.Facility DEFAULT_FACILITY
    • NILVALUE_SP

      public static final String NILVALUE_SP
      See Also:
    • outputLock

      private final Object outputLock
    • serverAddress

      private InetAddress serverAddress
    • port

      private int port
    • appName

      private String appName
    • hostname

      private String hostname
    • facility

      private SyslogHandler.Facility facility
    • syslogType

      private SyslogHandler.SyslogType syslogType
    • pid

      private final String pid
    • out

      private OutputStream out
    • protocol

      private SyslogHandler.Protocol protocol
    • useCountingFraming

      private boolean useCountingFraming
    • initializeConnection

      private boolean initializeConnection
    • outputStreamSet

      private boolean outputStreamSet
    • delimiter

      private String delimiter
    • useDelimiter

      private boolean useDelimiter
    • truncate

      private boolean truncate
    • maxLen

      private int maxLen
    • blockOnReconnect

      private boolean blockOnReconnect
  • Constructor Details

    • SyslogHandler

      public SyslogHandler() throws IOException
      The default class constructor.
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(String serverHostname, int port) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverHostname parameter on the port represented by the port parameter.
      Parameters:
      serverHostname - the server to send the messages to
      port - the port the syslogd is listening on
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(InetAddress serverAddress, int port) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverAddress - the server to send the messages to
      port - the port the syslogd is listening on
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(String serverHostname, int port, SyslogHandler.Facility facility, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverHostname - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(InetAddress serverAddress, int port, SyslogHandler.Facility facility, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverAddress - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(String serverHostname, int port, SyslogHandler.Facility facility, SyslogHandler.SyslogType syslogType, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverHostname - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      syslogType - the type of the syslog used to format the message
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(InetAddress serverAddress, int port, SyslogHandler.Facility facility, SyslogHandler.SyslogType syslogType, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverAddress - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      syslogType - the type of the syslog used to format the message
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(String serverHostname, int port, SyslogHandler.Facility facility, SyslogHandler.SyslogType syslogType, SyslogHandler.Protocol protocol, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverHostname - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      syslogType - the type of the syslog used to format the message
      protocol - the socket type used to the connect to the syslog server
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
    • SyslogHandler

      public SyslogHandler(InetAddress serverAddress, int port, SyslogHandler.Facility facility, SyslogHandler.SyslogType syslogType, SyslogHandler.Protocol protocol, String hostname) throws IOException
      Creates a new syslog handler that sends the messages to the server represented by the serverAddress parameter on the port represented by the port parameter.
      Parameters:
      serverAddress - the server to send the messages to
      port - the port the syslogd is listening on
      facility - the facility to use when calculating priority
      syslogType - the type of the syslog used to format the message
      protocol - the socket type used to the connect to the syslog server
      hostname - the name of the host the messages are being sent from see setHostname(String) for details on the hostname
      Throws:
      IOException - if an error occurs creating the UDP socket
  • Method Details

    • doPublish

      public final void doPublish(ExtLogRecord record)
      Description copied from class: ExtHandler
      Do the actual work of publication; the record will have been filtered already. The default implementation does nothing except to flush if the autoFlush property is set to true; if this behavior is to be preserved in a subclass then this method should be called after the record is physically written.
      Overrides:
      doPublish in class ExtHandler
      Parameters:
      record - the log record to publish
    • sendMessage

      private void sendMessage(byte[] header, ByteStringBuilder message, byte[] trailer) throws IOException
      Writes the message to the output stream. The message buffer is cleared after it's written.
      Parameters:
      message - the message to write
      Throws:
      IOException - if there is an error writing the message
    • close

      public void close()
      Description copied from class: ExtHandler
      Close all child handlers.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class ExtHandler
    • flush

      public void flush()
      Description copied from class: ExtHandler
      Flush all child handlers.
      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class ExtHandler
    • getAppName

      public String getAppName()
      Gets app name used when formatting the message in RFC5424 format. By default the app name is "java"
      Returns:
      the app name being used
    • setAppName

      public void setAppName(String appName)
      Sets app name used when formatting the message in RFC5424 format. By default the app name is "java"
      Parameters:
      appName - the app name to use
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • isBlockOnReconnect

      public boolean isBlockOnReconnect()
      Indicates whether or not a TCP or SSL TCP connection should block when attempting to reconnect.
      Returns:
      true if blocking is enabled, otherwise false
    • setBlockOnReconnect

      public void setBlockOnReconnect(boolean blockOnReconnect)
      Enables or disables blocking when attempting to reconnect a TCP or SSL TCP protocol.

      If set to true the publish methods will block when attempting to reconnect. This is only advisable to be set to true if using an asynchronous handler.

      Parameters:
      blockOnReconnect - true to block when reconnecting or false to reconnect asynchronously discarding any new messages coming in
    • isEscapeEnabled

      @Deprecated public boolean isEscapeEnabled()
      Deprecated.
      escaping message values is not required per RFC5424 and is no longer supported in this handler
      Checks whether or not characters below decimal 32, traditional US-ASCII control values expect DEL, are being escaped or not.
      Returns:
      false
    • setEscapeEnabled

      @Deprecated public void setEscapeEnabled(boolean escapeEnabled)
      Deprecated.
      escaping message values is not required per RFC5424 and is no longer supported in this handler
      Note: This method no longer does anything.

      Set to true to escape characters within the message string that are below decimal 32. These values are tradition US-ASCII control values. The values will be replaced in a #xxx format where xxx is the octal value of the character being replaced.

      Parameters:
      escapeEnabled - true to escape characters, false to not escape characters
    • getPid

      public String getPid()
      Returns the pid being used as the PROCID for RFC5424 messages.
      Returns:
      the pid
    • getPort

      public int getPort()
      Returns the port the syslogd is listening on.
      Returns:
      the port
    • setPort

      public void setPort(int port)
      Sets the port the syslogd server is listening on.
      Parameters:
      port - the port
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • getFacility

      public SyslogHandler.Facility getFacility()
      Returns the facility used for calculating the priority of the message.
      Returns:
      the facility
    • setFacility

      public void setFacility(SyslogHandler.Facility facility)
      Sets the facility used when calculating the priority of the message.
      Parameters:
      facility - the facility
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • getHostname

      public String getHostname()
      Returns the host name which is used when sending the message to the syslog.
      Returns:
      the host name
    • getMaxLength

      public int getMaxLength()
      Returns the maximum length, in bytes, of the message allowed to be sent. The length includes the header and the message.
      Returns:
      the maximum length, in bytes, of the message allowed to be sent
    • setMaxLength

      public void setMaxLength(int maxLen)
      Sets the maximum length, in bytes, of the message allowed to tbe sent. Note that the message length includes the header and the message itself.
      Parameters:
      maxLen - the maximum length, in bytes, allowed to be sent to the syslog server
    • getMessageDelimiter

      public String getMessageDelimiter()
      Returns the delimiter being used for the message if use message delimiter is set to true.
      Returns:
      the delimiter being used for the message
    • setMessageDelimiter

      public void setMessageDelimiter(String delimiter)
      Sets the message delimiter to be used if use message delimiter is set to true.
      Parameters:
      delimiter - the delimiter to use for the message
    • isUseMessageDelimiter

      public boolean isUseMessageDelimiter()
      Checks whether to append the message with a delimiter or not.
      Returns:
      true to append the message with a delimiter, otherwise false
    • setUseMessageDelimiter

      public void setUseMessageDelimiter(boolean useDelimiter)
      Whether to append the message with a delimiter or not.
      Parameters:
      useDelimiter - true to append the message with a delimiter, otherwise false
    • setHostname

      public void setHostname(String hostname)
      Sets the host name which is used when sending the message to the syslog.

      This should be the name of the host sending the log messages, Note that the name cannot contain any whitespace.

      The hostname should be the most specific available value first. The order of preference for the contents of the hostname is as follows:

      1. FQDN
      2. Static IP address
      3. hostname
      4. Dynamic IP address
      5. null
      Parameters:
      hostname - the host name
    • isUseCountingFraming

      public boolean isUseCountingFraming()
      Returns true if the message size should be prefixed to the message being sent.

      See http://tools.ietf.org/html/rfc6587 for more details on framing types.

      Returns:
      the message transfer type
    • setUseCountingFraming

      public void setUseCountingFraming(boolean useCountingFraming)
      Set to true if the message being sent should be prefixed with the size of the message.

      See http://tools.ietf.org/html/rfc6587 for more details on framing types.

      Parameters:
      useCountingFraming - true if the message being sent should be prefixed with the size of the message
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • setServerHostname

      public void setServerHostname(String hostname) throws UnknownHostException
      Sets the server address the messages should be sent to.
      Parameters:
      hostname - the hostname used to created the connection
      Throws:
      UnknownHostException - if no IP address for the host could be found, or if a scope_id was specified for a global IPv6 address.
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
      See Also:
    • getServerAddress

      public InetAddress getServerAddress()
      Returns the server address the messages are being sent to.
      Returns:
      the server address
    • setServerAddress

      public void setServerAddress(InetAddress serverAddress)
      Sets the server address the messages should be sent to.
      Parameters:
      serverAddress - the server address
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • getSyslogType

      public SyslogHandler.SyslogType getSyslogType()
      Returns the syslog type this handler is using to format the message sent.
      Returns:
      the syslog type
    • setSyslogType

      public void setSyslogType(SyslogHandler.SyslogType syslogType)
      Set the syslog type this handler should use to format the message sent.
      Parameters:
      syslogType - the syslog type
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission(control) or the handler is protected
    • getProtocol

      public SyslogHandler.Protocol getProtocol()
      The protocol used to connect to the syslog server
      Returns:
      the protocol
    • setProtocol

      public void setProtocol(SyslogHandler.Protocol type)
      Sets the protocol used to connect to the syslog server
      Parameters:
      type - the protocol
    • setOutputStream

      public void setOutputStream(OutputStream out)
      Sets the output stream for the syslog handler to write to.

      Setting the output stream closes any already established connections or open output streams and will not open any new connections until the output stream is set to null. The protocol, {@link #setServerAddress(java.net.InetAddress), server address}, server hostname or port have no effect when the output stream is set.

      Parameters:
      out - the output stream to write to
    • isTruncate

      public boolean isTruncate()
      Checks if the message should truncated if the total length exceeds the maximum length.
      Returns:
      true if the message should be truncated if too large, otherwise false
    • setTruncate

      public void setTruncate(boolean truncate)
      Set to true if the message should be truncated if the total length the maximum length.

      Set to false if the message should be split and sent as multiple messages. The header will remain the same for each message sent. The wrapping is not a word based wrap and could split words between log messages.

      Parameters:
      truncate - true to truncate, otherwise false to send multiple messages
    • setOutputStream

      private void setOutputStream(OutputStream out, boolean outputStreamSet)
    • safeClose

      static void safeClose(Closeable closeable)
    • safeFlush

      static void safeFlush(Flushable flushable)
    • findPid

      private static String findPid()
    • init

      private void init()
    • calculatePriority

      protected int calculatePriority(Level level, SyslogHandler.Facility facility)
    • createRFC5424Header

      protected byte[] createRFC5424Header(ExtLogRecord record) throws IOException
      Throws:
      IOException
    • createRFC3164Header

      protected byte[] createRFC3164Header(ExtLogRecord record) throws IOException
      Throws:
      IOException