Logging

HiveMQ implements a powerful Logback logging system that helps you monitor, diagnose, and troubleshoot your applications. The default HiveMQ logging configuration is suitable for most use cases. For information on how to change the default behavior, see Adjust Logging.

HiveMQ writes all log data to the log folder of your HiveMQ installation.

The current log file is named hivemq.log. The standard HiveMQ logging configuration uses a log rolling policy that archives the log file every day at midnight. HiveMQ archives the daily log files with the name hivemq.$DATE.log and stores each of the archived log files for 30 days.

Example default log file configuration

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${hivemq.log.folder}/hivemq.log</file>
        <append>true</append>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- daily rollover -->
            <fileNamePattern>${hivemq.log.folder}/hivemq.%d{yyyy-MM-dd}.log</fileNamePattern>
            <!-- keep 30 days' worth of history -->
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>%-30(%d %level)- %msg%n%ex</pattern>
        </encoder>
    </appender>

By default, HiveMQ deletes archived log files after 30 days. If you want to retain your log files longer, adjust the <maxHistory> setting or backup the files manually.

Example 1. Example HiveMQ log folder content

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

To protect against distributed denial-of-service attacks (DDoS), the default setting of HiveMQ does not log malicious client behavior. DDoS attacks can overload your system with superfluous log entries. If you want HiveMQ to log these entries, you can set your log level to DEBUG. HiveMQ logs many entries on the DEBUG level. When you select the DEBUG log level, we recommend that you monitor the size of your log file frequently.

HiveMQ stores information for key events in a separate log file. For more information, see Event Log.

Adjust Logging

The HiveMQ logging subsystem uses the standard Logback Java logging framework. Logback offers a variety of features that let you tailor your HiveMQ logging to meet your individual needs.

The Logback library defines 5 log levels that you can select from:

TRACE: Logs highly detailed information about a wide range of HiveMQ behaviors.
For example, TRACE - Metrics timer [com.hivemq.information.executor.idle] added.
The TRACE level logs the largest amount of information and is not recommended for production environments.
DEBUG: Logs information about the significant, normal, and insignificant HiveMQ behaviors.
For example, DEBUG - Setting shared subscriptions enabled to true.
The DEBUG level logs a large amount of information and is not recommended for production environments.
INFO: Logs information about runtime events of interest such as HiveMQ startup or shutdown. For example, INFO - Shutting down extension system or INFO - Started TCP Listener on address 0.0.0.0 and on port 1883. INFO is the default log level of HiveMQ.
WARN: Logs information about undesirable behaviors of HiveMQ that have not yet limited execution of normal operations. For example, WARN - The configured maximum qos (3) does not exist. It was set to (2) instead.
ERROR: Logs information about unexpected conditions and tasks that HiveMQ is unable to complete successfully. For example, ERROR - Could not read the configuration file /opt/hivemq/config.xml. Using default config.

Each log level has a corresponding logging method: trace(), debug(), info(), warn(), error().

If no log level is assigned, the logger inherits the level of its closest ancestor. The root logger defaults to DEBUG.

By default, HiveMQ scans the logback.xml file in the conf folder for changes every 60 seconds. HiveMQ applies the changes that you make to the logback.xml during runtime. You do not need to restart HiveMQ.

To change the frequency with which HiveMQ checks the logback.xml, adjust the scanPeriod setting. To turn off automatic scanning, set scan="false".

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

If you disable automatic scanning, you must restart HiveMQ to apply changes that you make to the logback.xml file.

Time-based Policy with Total Size Limit

To limit the total combined size of your log files as well as the number of days the files are stored, add a <totalSizeCap> property to your logging configuration.

Example time-based log rolling policy configuration with size cap

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${hivemq.log.folder}/hivemq.log</file>
        <append>true</append>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- daily rollover -->
            <fileNamePattern>${hivemq.log.folder}/hivemq.%d{yyyy-MM-dd}.log</fileNamePattern>
            <!-- keep 30 days' worth of history -->
            <maxHistory>30</maxHistory>
            <!-- maximum combined log file size is 30GB -->
            <totalSizeCap>30GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%-30(%d %level)- %msg%n%ex</pattern>
        </encoder>
    </appender>

Size and Time-based Policy with Total SIze Limit

To archive your log files by date, limit the size of each log file, and set an overall limit to the combined size of your log file, use a SizeAndTimeBasedRollingPolicy in your logging configuration. This configuration is useful for a variety of uses cases. For example, if your post-processing tools impose size limits on log files.

Example size and time-based rolling policy configuration

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
   ...
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <!-- rollover daily -->
      <fileNamePattern>mylog-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
       <!-- maximum size of a single log file is 100MB -->
       <maxFileSize>100MB</maxFileSize>
       <!-- keep 30 days worth of history -->
       <maxHistory>30</maxHistory>
      <!-- maximum combined log file size is 30GB -->
       <totalSizeCap>30GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>

The %i tag in <fileNamePattern> is mandatory.

If you only want to limit the combined size of log archives and do not need to limit the size of the individual log files, you can simply add a totalSizeCap property to your TimeBasedRollingPolicy.

Event Log

In addition to the information that HiveMQ provides in the hivemq.log file, HiveMQ records key events to a separate event.log file.

To record events, you must use the DEBUG log level.

The HiveMQ event log provides information for the following events:

Client connect
Client disconnect
Dropped message
Client session expiry

The current event log file is named event.log. The standard HiveMQ logging configuration uses a log rolling policy that archives the event log file when the size of the file reaches 100 MB.
HiveMQ archives event log files with the name event-$COUNT.log.gz. A maximum of 5 event log files can be archived at the same time. When the limit is reached, HiveMQ deletes the oldest file.

Example default event.log configuration

    <appender name="EVENT-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${hivemq.log.folder}/event.log</file>
        <append>true</append>
        <encoder>
            <pattern>%-24(%d)- %msg%n%ex</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
            <fileNamePattern>${hivemq.log.folder}/event-%i.log.gz</fileNamePattern>
            <minIndex>1</minIndex>
            <maxIndex>5</maxIndex>
        </rollingPolicy>
        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
            <maxFileSize>100MB</maxFileSize>
        </triggeringPolicy>
    </appender>

Client Connect

When an MQTT client successfully connects to the broker, HiveMQ logs an entry similar to the following statement:

2020-08-27 09:26:32,244 - Client ID: testClient, IP: 127.0.0.1, Clean Start: true, Session Expiry: 0 connected.

Client Disconnect

In MQTT 5, DISCONNECT packets can include an optional disconnect reason string. When an MQTT 5 client provides a reason string in the DISCONNECT packet, the HiveMQ log entry includes the reason string.

The log entry for a client disconnect that lacks a reason string is similar to the following example:

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

The log entry for an MQTT 5 client that provides a disconnect reason string is similar to this example:

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

Dropped Message

In MQTT, dropped messages are messages that the MQTT broker does not publish. Dropped messages can occur for various reasons. For more information, see Dropped Messages

The log entry for a dropped message is similar to this example:

2020-08-27 09:37:12,661 - Outgoing publish message was dropped. Receiving client: subscriber1, topic: test, qos: 1, reason: The client message queue is full.

Client Session Expiry

The session expiry defines the length of time in seconds that can pass after the client disconnects until the session of the client expires. If a client with the same client ID reconnects before the defined length of time elapses, the session expiry timer resets. For more information, see Session Expiry.

When HiveMQ removes an expired client session from its persistence, HiveMQ logs an entry similar to the following statement:

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 timestamp at the beginning of the expiry log entry shows when HiveMQ removed the expired session from the persistence and created the log output.
The second timestamp shows the moment when the session expired.

Extension Log Files

By default, HiveMQ logs information to the hivemq.log file for each HiveMQ extension that you run. The additional entries can make it more difficult to evaluate information in the log output. The use of separate log files for your HiveMQ extensions can make it easier for you to efficiently monitor and troubleshoot your applications.

Add Extension Log File

The following example shows you how to create a separate log file for the HiveMQ File RBAC Extension. The steps are similar for all HiveMQ extensions.

Prerequisites

An installed version of the HiveMQ File RBAC Extension.
For more information, see File RBAC Extension and File RBAC Extension GitHub repository.
Once you have successfully installed the RBAC extension, a log entry similar to the following statement confirms your installation.

INFO  - Extension "File Role Based Access Control Extension" version 4.0.0 started successfully.

Extension Log File Configuration

To create a separate log file for the extension, you must add an appropriately defined appender to the logback.xml of your HiveMQ configuration.

The additional appender and logger configurations specify the output file, rolling policy, log pattern, and logger that are used to log extension information.

The following code example places a log file named file-rbac.log in the log folder of your HiveMQ installation.

The rollingPolicy in the example archives the log file every day at midnight, compresses the file, and stores each log file for 30 days.

Example appender for RBAC extension log file configuration

<appender name="FILE-RBAC" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!-- name and location of the log file -->
        <file>${hivemq.home}/log/file-rbac.log</file>
        <append>true</append>
        <encoder>
            <pattern>%-30(%d [%thread]) - %level - %logger{32} - %msg%n%ex</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- daily rollover -->
            <fileNamePattern>${hivemq.home}/log/pval_plugin_event.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <!-- keep 30 days' worth of history -->
            <maxHistory>30</maxHistory>
        </rollingPolicy>
</appender>

The following example logger configuration adds the required logger.

Example RBAC extension logger configuration

	<logger name="com.hivemq.extensions.rbac" level="INFO" additivity="false">
	<appender-ref ref="FILE-RBAC"/>
</logger>

In the logger configuration, the logger name must match the package name of the associated extension and the appender-ref must match the name of the defined appender.

Extension Log File Verification

To verify creation of the extension log file, go to the log folder of your HiveMQ installation. Based on the scanPeriod that is set in the logback.xml file in your conf folder, HiveMQ scans the changes and updates your configuration. If you have disabled automatic scanning (scan=false), you must restart HiveMQ to apply the changes.

Look for a new file named file-rbac.log in the log directory.

Open the file-rbac.log file and confirm that an extension start entry or other INFO entries are visible.

Syslog

The HiveMQ logging subsystem can log to a Syslog server. Use of a Syslog server allows you to consolidate log files from multiple HiveMQ broker nodes into a single log file. A configurable prefix in the log statements ensures that each statement can be associated with the HiveMQ node on which it was created. The unified log view simplifies the management and analysis of your logs and makes it easier to debug large HiveMQ cluster deployments.

For more information, see A Quick guide to Syslog and HiveMQ.

To activate Syslog, append your logback.xml file with the following configuration.
Replace $IP-Adress with the address of your Syslog server, and replace X with the identifier of the node.

Example Syslog appender configuration

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

        // IP-Address of your syslog server
        <syslogHost>$IP-Address</syslogHost>

        <facility>user</facility>
        // replace X with the node identifier
        <suffixPattern>[nodeX] %-30(%d %level)- %msg%n%ex</suffixPattern>
    </appender>

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