Logging

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

The current log file is named hivemq.log. The standard log configuration uses a log-rolling policy that archives the log file daily at midnight.
The name of the archived log file is formatted as follows: hivemq.$DATE.log.
HiveMQ retains archived log files for 30 days and then deletes the file. If you want to archive the files for a longer period of time, you must manually backup your log files.

For specific events, HiveMQ maintains a separate Event Log .

The following example shows the contents of a typical log subfolder:

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 malicious client behavior. This policy protects your system from the harm that immense spamming of log files can cause. For example, a DDoS attack.
To have HiveMQ log these entries, set the log level to DEBUG. Be aware that HiveMQ logs many entries at the DEBUG level. If you set your log level to DEBUG, we strongly recommend that you monitor the size of your regularly.

Change Log Behavior

The HiveMQ logging subsystem uses the standard Java logging framework Logback. The default log configuration is suitable for most use cases. If desired, you can adjust the logging behavior to suit your individual needs.

By default, HiveMQ scans the logback.xml file in the conf folder of your HiveMQ installation for changes every 60 seconds and adjusts the logging behavior at run time. In the logback.xml file, you can adjust scan frequency or turn off automatic scanning.

To turn off automatic scanning, set the scan option to false: scan="false".

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

To limit the size of your log files, you can add a maximum file-size to the log-rolling policy in the file appender configuration of your logback.xml file.

Example file-size based log-rolling policy
    <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 in the <fileNamePattern> tag is mandatory.

If you add a <maxHistory> configuration, you limit the total log size to <maxHistory> * <maxFileSize>.

Event Log

HiveMQ logs the following events in the event log file:

  • Client connection

  • Client disconnection (with MQTT5 DISCONNECT reason string, if present)

  • Dropped message

  • Client session expiry

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

By default, the log level for events in the logback.xml file is DEBUG. If you decrease this level for an event, the event is not logged in the event.log file. For example, if you change the log level to INFO or WARN.

Disconnect Event Log

If an MQTT 5 client uses a reason string in the DISCONNECT packet, the log statement includes the reason string.

The default log statement upon disconnect has the following format:

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 that uses a reason string has the following format:

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 can pass after the client disconnected before its session expires. If the client (same client ID) reconnects before the expiry time ends, HiveMQ resets the timer.

When HiveMQ removes an expired client session from its persistence, a statement with the following format is logged:

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.
The first timestamp in the statement shows when HiveMQ removed the expired session from the persistence and created the log output. The second timestamp shows the time that the session expired.

Syslog

The HiveMQ logging subsystem also makes it possible to log to a syslog server. This ability is particularly useful for HiveMQ cluster deployments. The syslog server can receive log messages from multiple HiveMQ nodes simultaneously and display them in a single view. This unified view simplifies debugging for large deployments.

To activate syslog, extend the logback.xml file with the following configuration:

Syslog appender
    <configuration>
        ...

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

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

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

        </appender>

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

        ...
   </configuration>