Logging

Per default, HiveMQ writes all log data to the log subfolder.

The most current log file is named hivemq.log. The standard log configuration has a log rolling policy, which archives the log file at midnight. For each day an archived log file is created with the name hivemq.$DATE.log. A log file will be archived for 30 days before it gets deleted. It is recommended to manually backup the log files if you want to archive them longer.

For specific events a separate Event Log exists.

The following example shows typical contents of the log subfolder.

Example 1. log folder contents
hivemq.log
hivemq.2018-05-11.log
hivemq.2018-05-12.log
hivemq.2018-05-13.log
event.log
event-1.log.gz
event-2.log.gz
event-3.log.gz
event-4.log.gz
By default HiveMQ does not log any malicious client behaviour. Otherwise DDoS attacks could be harmful to your system due to an immense spamming of log files. If you want HiveMQ to log these entries, set the log level to DEBUG. Be aware that HiveMQ will log many entries on this log level. You should monitor your log file sizes when setting the log level to DEBUG.

Changing the log behaviour

The HiveMQ Logging Subsystem uses the standard Java logging framework Logback. While the default log configuration is suitable for most use cases, you might want to change the logging behaviour so it suits your use case.

By default HiveMQ will scan the logback.xml file in the conf folder for changes every 60 seconds and adjust the logging behaviour at run time. This auto-scan period can be changed or completely turned off at the beginning of the logback.xml file.

If you set scan="false", scanning will be turned off.

<configuration scan="true" scanPeriod="60 seconds">

If you want to limit the file size of your log files, you can add the following policy to the rolling policy in your file appender configuration.

File size based rollover example
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        ...
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${hivemq.home}/log/hivemq.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <timeBasedFileNamingAndTriggeringPolicy
                    class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                <!-- maximum size a single log file can have -->
                <maxFileSize>100MB</maxFileSize>
            </timeBasedFileNamingAndTriggeringPolicy>
            ...
        </rollingPolicy>
        ...
    </appender>
The %i tag in <fileNamePattern> is mandatory.

If you add a <maxHistory> configuration you are effectively limiting the total log size to <maxHistory> * <maxFileSize>.

Event Log

Following events are logged in the event log file:

  • Client connection

  • Client disconnection

  • Dropping of messages

  • Client session expiry

The most current event log file is named event.log. The standard log configuration has a log rolling policy, which archives the event log file when it reaches a size of 100MB. The archives are named event-$COUNT.log.gz. A maximum amount of 5 event log files will be archived at the same time, the oldest file will be deleted once this maximum is exceeded.

Syslog

The HiveMQ Logging Subsystem also offers the ability to log to a syslog server. This can be very handy for HiveMQ cluster deployments. The syslog server can receive log messages from multiple HiveMQ nodes simultaneously and displays them in a single view, which simplifies the debugging for large deployments.

To activate syslog you need to extend the logback.xml file with the following configuration.

Syslog appender
    <configuration>
        ...

        <appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender">

            <!-- Add here the ip address of your syslog server -->
            <syslogHost> ip address </syslogHost>

            <facility>USER</facility>
            <suffixPattern>[%thread] %logger %msg</suffixPattern>

        </appender>

        <root level="INFO">
            <appender-ref ref="SYSLOG" />
        </root>

        ...
   </configuration>