HiveMQ Edge Logging

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

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

Example default log file configuration
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- daily rollover -->
            <!-- keep 30 days' worth of history -->
            <pattern>%-30(%d %level)- %msg%n%ex</pattern>
If you want to retain your log files longer than the default (30 days), we recommend you adjust the <maxHistory> setting or backup the files manually.

For information on specific events, see HiveMQ Edge Event Log.

Example 1. Example HiveMQ Edge log subfolder content
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. To have HiveMQ Edge log these entries for further inspection, set your log level to DEBUG. HiveMQ Edge logs many entries on the DEBUG level. If you select the DEBUG log level, we recommend that you monitor the size of your log file frequently.

Change HiveMQ Edge log behavior

The HiveMQ logging subsystem uses the standard Java logging framework Logback. The HiveMQ Edge 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 Edge scans the logback.xml file in the conf folder for changes every 60 seconds and adjusts the logging behavior at run time. This auto-scan period can be changed or completely turned off in the logback.xml file.

To turn off automatic scanning, set scan="false" in the logback.xml file.

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

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

Example file-size based rollover configuration
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <!-- maximum size a single log file can have -->
The %i tag in <fileNamePattern> is mandatory.

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

HiveMQ Edge 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 shows the reason string.

The default 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: 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: disconnected gracefully. Reason given by client: This is my reason string

Client Session Expiry

The session expiry value 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.

The HiveMQ Edge log entry when an expired client session is removed from its persistence is similar to the following example:

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 log entry shows 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 expired.

HiveMQ Edge Syslog

The HiveMQ Edge logging subsystem also offers the ability to 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. The unified log view simplifies the management and analysis of your logs and makes it easier to debug large deployments.

To activate Syslog, extend your logback.xml file with the following configuration.

Syslog appender

        <appender name="SYSLOG" class="">

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

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


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