Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hivemq/hivemq-mqtt-message-log-extension

The HiveMQ MQTT Message Log Extension provides the possibility to follow up on any clients communicating with the broker on the terminal.
https://github.com/hivemq/hivemq-mqtt-message-log-extension

extension hivemq hivemq-extension logging mqtt

Last synced: about 2 months ago
JSON representation

The HiveMQ MQTT Message Log Extension provides the possibility to follow up on any clients communicating with the broker on the terminal.

Awesome Lists containing this project

README 

        
:hivemq-blog-tools: http://www.hivemq.com/mqtt-toolbox

:hivemq-support: http://www.hivemq.com/support/

:hivemq-extension-download: https://www.hivemq.com/extension/mqtt-message-log-extension/



= HiveMQ MQTT Message Log Extension



image:https://img.shields.io/badge/Extension_Type-Logging-orange?style=for-the-badge[Extension Type]

image:https://img.shields.io/github/v/release/hivemq/hivemq-mqtt-message-log-extension?style=for-the-badge[GitHub release (latest by date),link=https://github.com/hivemq/hivemq-mqtt-message-log-extension/releases/latest]

image:https://img.shields.io/github/license/hivemq/hivemq-mqtt-message-log-extension?style=for-the-badge&color=brightgreen[GitHub,link=LICENSE]

image:https://img.shields.io/github/actions/workflow/status/hivemq/hivemq-mqtt-message-log-extension/check.yml?branch=master&style=for-the-badge[GitHub Workflow Status,link=https://github.com/hivemq/hivemq-mqtt-message-log-extension/actions/workflows/check.yml?query=branch%3Amaster]



== 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:*



[cols="6,2,2"]

|===

|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-extension-download}[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 <> 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 {hivemq-blog-tools}[MQTT client] of your choice.

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



[[example]]

== Examples



=== Verbose CONNECT message with payload



[source,bash]

----

"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



[source,bash]

----

"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 {hivemq-support}[support^].



== Contributing



If you want to contribute to HiveMQ MQTT Message Log Extension, see the link:CONTRIBUTING.md[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 link:LICENSE[here].