HiveMQ MQTT Message Log Extension

Prerequisites

• HiveMQ Enterprise Edition (EE) 4.2.0 or later

• HiveMQ Community Edition (CE) 2020.1 or later

Purpose

The HiveMQ MQTT Message Log Extension provides custom logging events on clients communicating with the broker. This is useful for debugging and development purposes.

The extension logs the following events:

Event	Config Property	Minimum Version
A client connects to HiveMQ	client-connect	4.2 EE or 2020.1 CE
A client disconnects from HiveMQ	client-disconnect	4.2 EE or 2020.1 CE
A client sends a PUBLISH message	publish-received	4.2 EE or 2020.1 CE
A client sends a SUBSCRIBE message	subscribe-received	4.2 EE or 2020.1 CE
HiveMQ sends a PUBLISH message to a client	publish-send	4.2 EE or 2020.1 CE
A client sends an UNSUBSCRIBE message	unsubscribe-received	4.3 EE or 2020.1 CE
A client send a PING request	ping-request-received	4.3 EE or 2020.1 CE
A client completes a received QoS 1 PUBLISH with a PUBACK message	puback-received	4.3 EE or 2020.1 CE
A client acknowledges the reception of a QoS 2 PUBLISH with a PUBREC message	pubrec-received	4.3 EE or 2020.1 CE
A client completes a sent QoS 2 PUBLISH with a PUBREL message	pubrel-received	4.3 EE or 2020.1 CE
A client completes a received QoS 2 PUBLISH with a PUBCOMP message	pubcomp-received	4.3 EE or 2020.1 CE
HiveMQ sends a CONNACK message to a client	connack-send	4.3 EE or 2020.1 CE
HiveMQ disconnects a client with a DISCONNECT message	client-disconnect	4.3 EE or 2020.1 CE
HiveMQ sends a SUBACK message to a client	suback-send	4.3 EE or 2020.1 CE
HiveMQ sends an UNSUBACK message to a client	unsuback-send	4.3 EE or 2020.1 CE
HiveMQ sends a PING response to a client	ping-response-send	4.3 EE or 2020.1 CE
HiveMQ completes a received QoS 1 PUBLISH with a PUBACK message	puback-send	4.3 EE or 2020.1 CE
HiveMQ acknowledges the reception of a QoS 2 PUBLISH with a PUBREC message	pubrec-send	4.3 EE or 2020.1 CE
HiveMQ completes a sent QoS 2 PUBLISH with a PUBREL message	pubrel-send	4.3 EE or 2020.1 CE
HiveMQ completes a received QoS 2 PUBLISH with a PUBCOMP message	pubcomp-send	4.3 EE or 2020.1 CE

Installation

• Download the extension from the HiveMQ Marketplace.

• Copy the content of the zip file to the extensions folder of your HiveMQ nodes.

• Configure the extension by adding a config.xml file in the extension’s conf folder.

  • For your convenience, we provide an example configuration conf/examples/config.xml that you can copy and modify as desired.

  • The file must be located in HIVEMQ_HOME/extensions/hivemq-mqtt-message-log-extension/conf/config.xml.

Note	Starting with release 1.2.0 of the extension, the legacy configuration file mqttMessageLog.properties is deprecated. Support for the legacy configuration will be removed in a future release.

Configuration

Event Configuration

By default, all MQTT events are logged. It is possible to opt out of specific log event types by adding a config.xml file to your hivemq-mqtt-message-log-extension/conf folder. An example configuration file is available in conf/examples/, which removes the logging of PUBLISH messages.

General Configuration

Config Property	Description	Default
verbose	Log detailed information about an MQTT event	false
payload	Log the payload of a message	true

Normally, events only log important information. Set the verbose property to true to log all available information. You can see the difference between normal logging and verbose logging in the Examples section.

Caution

use verbose=true very carefully as it will flood your log immediately.

Set the payload property to false if you want to suppress logging payloads (i.e. for publish-received, publish-send, and will messages).

First Steps

Connect with an MQTT client of your choice. You should see a log message with its client identifier, MQTT version, clean start flag and session expiry interval.

Examples

Verbose CONNECT message with payload

"17:26:23.602 INFO - Received CONNECT from client 'clientid': Protocol version: 'V_5', Clean Start: 'false',
Session Expiry Interval: '10000', Keep Alive: '20000', Maximum Packet Size: '40000',
Receive Maximum: '30000', Topic Alias Maximum: '50000', Request Problem Information: 'true',
Request Response Information: 'false',  Username: 'the username', Password: 'the password',
Auth Method: 'auth method', Auth Data (Base64): 'YXV0aCBkYXRh',
User Properties: [Name: 'name0', Value: 'value0'], [Name: 'name1', Value: 'value1'],
Will: { Topic: 'willtopic', Payload: 'payload', QoS: '1', Retained: 'false', Message Expiry Interval: '1234',
Duplicate Delivery: 'false', Correlation Data: 'data', Response Topic: 'response topic',
Content Type: 'content type', Payload Format Indicator: 'UTF_8', Subscription Identifiers: '[1, 2, 3, 4]',
User Properties: [Name: 'name0', Value: 'value0'], [Name: 'name1', Value: 'value1'],
[Name: 'name2', Value: 'value2'], Will Delay: '100' }"

Basic CONNECT message

"17:26:23.602 INFO - Received CONNECT from client 'clientid': Protocol version: 'V_5', Clean Start: 'false', Session Expiry Interval: '10000'"

Need Help?

If you encounter any problems, we are happy to help. The best place to get in contact is our support.

Contributing

If you want to contribute to HiveMQ MQTT Message Log Extension, see the contribution guidelines.

License

HiveMQ MQTT Message Log Extension is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.