​

Diagnostics

​

Diagnostic Mode

​

Starting in Diagnostic Mode

​

Linux/Unix/macOS

./bin/diagnostics.sh

​

Windows

bin\diagnostics.bat

​

What Diagnostic Mode Does

1. Enables enhanced JVM diagnostics
   • Heap dump on OutOfMemoryError
   • Error log files for JVM crashes
   • Crash on OutOfMemoryError (for immediate detection)
2. Activates diagnostic flag
   • Sets -DdiagnosticMode=true system property
   • Can be used by extensions for conditional debug behavior
3. Displays detailed startup information
   • HIVEMQ_HOME directory
   • Java options (JAVA_OPTS)
   • Java version
   • Configuration details

​

Diagnostic Script Configuration

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=$HIVEMQ_HEAPDUMP_FOLDER/heap-dump.hprof
-XX:ErrorFile=$HIVEMQ_HEAPDUMP_FOLDER/hs_err_pid%p.log
-XX:+CrashOnOutOfMemoryError

• diagnosticMode=true - Enables diagnostic mode
• hivemq.home - HiveMQ installation directory
• java.net.preferIPv4Stack=true - IPv4 preference

• Enabled by default (can be disabled with HIVEMQ_JMX_ENABLED=false)
• Port: 9010 (configurable via HIVEMQ_JMX_PORT)
• No authentication (development default)
• Remote access enabled

​

Environment Variables

# Set custom heap dump location
export HIVEMQ_HEAPDUMP_FOLDER=/path/to/dumps

# Set HiveMQ home (auto-detected by default)
export HIVEMQ_HOME=/opt/hivemq

# Configure JMX
export HIVEMQ_JMX_ENABLED=true
export HIVEMQ_JMX_PORT=9010

# Add custom Java options
export JAVA_OPTS="-Xmx4g -Xms4g"

​

Requirements

​

Java Version

if [ "$JAVA_VERSION" -lt 11 ]; then
    echo 'ERROR! HiveMQ requires at least Java version 11.'
    exit 1
fi

​

Platform-Specific Requirements

• Bash shell
• Java Runtime Environment (JRE) 11+
• Read/write permissions on HIVEMQ_HOME

• Administrator rights (recommended)
• Java Runtime Environment (JRE) 11+
• Read/write permissions on HIVEMQ_HOME

​

Diagnostic Outputs

​

Heap Dumps

$HIVEMQ_HEAPDUMP_FOLDER/heap-dump.hprof

• Eclipse Memory Analyzer (MAT)
• VisualVM
• JProfiler
• YourKit

​

Error Logs

$HIVEMQ_HEAPDUMP_FOLDER/hs_err_pid<pid>.log

• Stack trace at crash point
• Thread information
• Memory state
• JVM configuration
• System information

​

Troubleshooting Common Issues

​

Memory Issues

​

OutOfMemoryError

• HiveMQ crashes with OOM error
• Heap dump generated

1. Start in diagnostic mode
2. Reproduce the issue
3. Analyze heap dump with MAT or VisualVM

• Too many retained messages
• Large message queues for disconnected clients
• Memory leak in custom extension
• Insufficient heap size

# Increase heap size
export JAVA_OPTS="-Xmx8g -Xms8g"

# Start in diagnostic mode
./bin/diagnostics.sh

​

Connection Issues

​

Enable Connection Debug Logging

<logger name="com.hivemq.bootstrap.netty" level="DEBUG"/>
<logger name="io.netty" level="DEBUG"/>
<logger name="com.hivemq.mqtt.handler.connect" level="TRACE"/>

​

Check Port Availability

# Linux/macOS
netstat -an | grep 1883
lsof -i :1883

# Windows
netstat -an | findstr 1883

​

Message Flow Issues

​

Enable Message Handler Logging

<logger name="com.hivemq.mqtt.handler.publish" level="DEBUG"/>
<logger name="com.hivemq.mqtt.handler.subscribe" level="DEBUG"/>
<logger name="com.hivemq.metrics.handler" level="DEBUG"/>

​

Monitor Metrics

• com.hivemq.messages.dropped.count - Should be 0
• com.hivemq.mqtt.connection.not-writable.current - Should be low
• Message counters for throughput

​

Persistence Issues

​

Enable Persistence Logging

<logger name="com.hivemq.persistence" level="DEBUG"/>
<logger name="jetbrains.exodus" level="INFO"/>

​

Check Disk Space

# Linux/macOS
df -h $HIVEMQ_HOME/data

# Windows
dir "C:\Program Files\hivemq\data"

​

Extension Issues

​

Enable Extension Logging

<logger name="com.hivemq.extensions" level="DEBUG"/>
<logger name="com.hivemq.extension.sdk" level="DEBUG"/>

​

Check Extension Loading

INFO - Extension <extension-name> version <version> started successfully.

​

Performance Diagnostics

​

Thread Dumps

# Find HiveMQ process ID
jps -l | grep hivemq

# Capture thread dump
jstack <pid> > threaddump.txt

# Or multiple thread dumps
for i in {1..5}; do jstack <pid> > threaddump_$i.txt; sleep 5; done

​

GC Logging

export JAVA_OPTS="$JAVA_OPTS -Xlog:gc*:file=gc.log:time,uptime:filecount=10,filesize=10M"

​

JMX Monitoring

• Heap usage
• Thread count
• GC activity
• CPU usage
• Custom HiveMQ metrics

​

Diagnostic Checklist

• Start HiveMQ in diagnostic mode
• Enable appropriate debug logging
• Monitor JMX metrics
• Check log files for errors
• Verify Java version (11+)
• Check disk space availability
• Review heap dump if OOM occurred
• Capture thread dumps if hanging
• Monitor GC activity
• Test with minimal configuration
• Disable extensions to isolate issues

​

Getting Help

​

Information to Collect

1. Version Information
   • HiveMQ version
   • Java version
   • Operating system
2. Logs
   • HiveMQ logs with DEBUG level
   • JVM error logs
   • GC logs
3. Configuration
   • config.xml
   • logback.xml
   • Extension configurations
4. Diagnostic Data
   • Thread dumps
   • Heap dumps (if OOM)
   • JMX metrics snapshot
5. Reproduction Steps
   • Minimal configuration to reproduce
   • Load characteristics
   • Timeline of events

​

Community Support

• GitHub Issues: HiveMQ Community Edition
• HiveMQ Community Forum
• Stack Overflow (tag: hivemq)

​

See Also

• Logging Configuration - Configure detailed logging
• Monitoring - JMX monitoring setup
• Metrics Reference - Available metrics for diagnostics