Logging

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

Note

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>

Important

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 (with MQTT5 DISCONNECT reason string if present)

• 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.

Disconnect Event Log

When an MQTT 5 client uses a reason string in the DISCONNECT packet, the log statement will show this reason string.

The default log statement upon disconnect looks like this:

2018-08-14 08:41:37,576 - Client ID: testClient, IP:127.0.0.1 disconnected gracefully.

A log statement for an MQTT 5 client using a reason string looks like this:

2018-08-14 08:44:19,172 - Client ID: testClient, IP:127.0.0.1 disconnected gracefully. Reason given by client: This is my reason string

Client Session Expiry

The session expiry describes the amount of time (in seconds) that has to pass after the client disconnected before its session expires. In case the client (same client ID) reconnects before the expiry time ends, the timer is reset.

A statement like the following will be logged when HiveMQ removes an expired client session from its persistence.

2018-08-09 17:39:39,776 - Client ID: subscriber1 session has expired at 2018-08-09 17:39:26. All persistent data for this client has been removed.

Warning

The timestamp at the beginning illustrates the fixed time when HiveMQ removed the expired session from the persistence and created the log output. The second timestamp refers to the actual time the session has been expired.

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>