Logging Configuration
HiveMQ Community Edition uses Logback as its logging framework, providing flexible and powerful logging configuration capabilities.
Default Configuration
HiveMQ ships with a default Logback configuration located at:
src/main/resources/logback.xml
- Console appender with formatted output
- INFO level logging for most components
- Special log levels for third-party libraries
- Migration warnings
Logback Configuration File
Default logback.xml
<configuration scan="false">
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%-30(%d %level)- %msg%n%ex</pattern>
</encoder>
</appender>
<logger name="migrations" level="WARN" additivity="false">
<appender-ref ref="CONSOLE"/>
</logger>
<root level="INFO">
<appender-ref ref="CONSOLE"/>
</root>
<logger name="jetbrains.exodus" level="WARN"/>
<logger name="org.eclipse.jetty" level="ERROR"/>
<logger name="com.google.common.util.concurrent.Futures.CombinedFuture" level="OFF"/>
<logger name="oshi" level="ERROR"/>
</configuration>
Log Levels
Available Log Levels
Logback supports the following log levels (from most to least verbose):
- TRACE - Very detailed debugging information
- DEBUG - Detailed debugging information
- INFO - Informational messages (default)
- WARN - Warning messages for potentially problematic situations
- ERROR - Error messages for serious problems
- OFF - Disable logging
Default Log Levels
| Component | Level | Purpose |
|---|
| Root | INFO | Default for all HiveMQ components |
| migrations | WARN | Database migration warnings |
| jetbrains.exodus | WARN | Persistence library messages |
| org.eclipse.jetty | ERROR | HTTP server errors only |
| com.google.common.util.concurrent.Futures.CombinedFuture | OFF | Suppress Guava future warnings |
| oshi | ERROR | System metrics library errors |
Customizing Logging
Changing Log Levels
To enable debug logging for HiveMQ components:
<configuration scan="false">
<!-- Existing appenders -->
<!-- Enable DEBUG for all HiveMQ classes -->
<logger name="com.hivemq" level="DEBUG"/>
<root level="INFO">
<appender-ref ref="CONSOLE"/>
</root>
</configuration>
Component-Specific Logging
Enable detailed logging for specific components:
<!-- Debug MQTT message processing -->
<logger name="com.hivemq.mqtt.handler" level="DEBUG"/>
<!-- Debug persistence operations -->
<logger name="com.hivemq.persistence" level="DEBUG"/>
<!-- Debug metrics collection -->
<logger name="com.hivemq.metrics" level="DEBUG"/>
<!-- Debug client connections -->
<logger name="com.hivemq.bootstrap.netty" level="DEBUG"/>
Appenders
Console Appender
The default console appender outputs to standard output:
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%-30(%d %level)- %msg%n%ex</pattern>
</encoder>
</appender>
%-30(%d %level) - Date and log level (left-aligned, 30 chars)%msg - Log message%n - Newline%ex - Exception stack trace (if present)
File Appender
To log to a file instead of console:
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>hivemq.log</file>
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="FILE"/>
</root>
Rolling File Appender
For production environments, use a rolling file appender:
<appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/hivemq.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<!-- Daily rollover -->
<fileNamePattern>logs/hivemq.%d{yyyy-MM-dd}.log</fileNamePattern>
<!-- Keep 30 days of history -->
<maxHistory>30</maxHistory>
<!-- Maximum size of all log files -->
<totalSizeCap>10GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
Async Appender
For high-throughput scenarios, wrap appenders with async appender:
<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
<queueSize>512</queueSize>
<discardingThreshold>0</discardingThreshold>
<appender-ref ref="ROLLING" />
</appender>
<root level="INFO">
<appender-ref ref="ASYNC"/>
</root>
Common Pattern Elements
| Pattern | Description | Example |
|---|
%d | Date and time | 2024-03-15 14:30:45 |
%d{ISO8601} | ISO8601 format | 2024-03-15T14:30:45.123Z |
%level | Log level | INFO, DEBUG, ERROR |
%-5level | Log level (padded) | INFO , DEBUG |
%logger | Logger name | com.hivemq.bootstrap.HiveMQServer |
%logger{36} | Abbreviated logger | c.h.bootstrap.HiveMQServer |
%thread | Thread name | main, pool-1-thread-1 |
%msg | Log message | Actual log message |
%n | Newline | Platform-specific newline |
%ex | Exception | Full stack trace |
JSON Logging
For structured logging (useful with log aggregation tools):
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
</appender>
Requires adding logstash-logback-encoder dependency to your HiveMQ setup.
Dynamic Log Level Changes
Enable Configuration Scanning
Enable automatic configuration reload:
<configuration scan="true" scanPeriod="30 seconds">
<!-- Configuration -->
</configuration>
Via JMX
Log levels can also be changed at runtime using JMX MBeans (if JMX is enabled).
Troubleshooting
Enable Debug Logging
For troubleshooting issues:
<logger name="com.hivemq" level="DEBUG"/>
<logger name="com.hivemq.mqtt.handler" level="TRACE"/>
Common Debug Scenarios
Connection Issues:
<logger name="com.hivemq.bootstrap.netty" level="DEBUG"/>
<logger name="io.netty" level="DEBUG"/>
<logger name="com.hivemq.security" level="DEBUG"/>
<logger name="com.hivemq.extensions.auth" level="DEBUG"/>
<logger name="com.hivemq.mqtt.handler.publish" level="DEBUG"/>
<logger name="com.hivemq.mqtt.handler.subscribe" level="DEBUG"/>
<logger name="com.hivemq.persistence" level="DEBUG"/>
<logger name="jetbrains.exodus" level="INFO"/>
Best Practices
Production Logging
- Use INFO level for normal operations
- Enable file appenders with rotation
- Set size limits to prevent disk exhaustion
- Use async appenders for better performance
- Suppress verbose libraries (Jetty, Netty, etc.)
- Monitor log file sizes and rotation
Development Logging
- Use DEBUG or TRACE for detailed information
- Console appender for immediate feedback
- Enable HiveMQ component logging as needed
- Disable scanning for better performance in dev
Security Considerations
- Avoid logging sensitive data (passwords, tokens, PII)
- Be cautious with TRACE level in production
- Ensure log files have appropriate permissions
- Consider log encryption for sensitive environments
Diagnostic Mode
HiveMQ can be started in diagnostic mode with enhanced logging. See Diagnostics for details.
See Also
