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