Skip to main content

Turning on Debug Logging

Mango uses Apache Log4j2 for its logging framework. By default, Mango logs at the info level, which captures normal operational events. When troubleshooting specific subsystems, you can enable debug or trace level logging by providing a custom log4j2.xml configuration file.

Three Steps to Start Debugging​

Step 1: Download the Log4j2 Configuration File​

Open a terminal and navigate to your Mango data directory, then download the default log4j2.xml template.

Linux and Mac:

cd MA_HOME
wget https://docs-v5.radixiot.com/assets/files/5.0.x/log4j2.xml

Windows:

cd MA_HOME
curl -O https://docs-v5.radixiot.com/assets/files/5.0.x/log4j2.xml

Step 2: Add Debug Loggers​

Open log4j2.xml and insert <AsyncLogger> entries between the <Loggers> tags for the subsystems you want to debug. Examples are provided below for common modules.

Step 3: Enable the Custom Configuration​

Open your mango.properties file and set:

log4j2.configurationFile=log4j2.xml

The path is relative to your data directory (paths.data). You may also provide an absolute path. Restart Mango for the changes to take effect.

Module-Specific Debug Loggers​

BACnet​

<AsyncLogger includeLocation="true" name="com.serotonin.bacnet4j" level="debug"/>
<AsyncLogger includeLocation="true" name="com.serotonin.ma.bacnet" level="debug"/>

SNMP​

<AsyncLogger includeLocation="true" name="com.serotonin.m2m2.snmp" level="debug"/>
<AsyncLogger includeLocation="true" name="org.snmp4j" level="debug"/>

Haystack​

<AsyncLogger includeLocation="true" name="com.infiniteautomation.mango.haystack" level="debug"/>
<AsyncLogger includeLocation="true" name="org.projecthaystack" level="debug"/>

Suppress Poll Aborted Logs​

If data source poll-aborted messages are filling your logs, you can suppress them:

<AsyncLogger includeLocation="true" name="com.serotonin.m2m2.rt.dataSource.PollingDataSource" level="error"/>

Log4j2 Log Levels​

LevelDescription
traceFinest-grain logging. Produces very large log files; use sparingly.
debugDetailed diagnostic output. Use the most specific category possible to limit log volume.
infoDefault level for most Mango subsystems. Normal operational messages.
warnWarning conditions that may require attention but do not prevent operation.
errorError conditions that indicate a failure in a specific operation.
fatalCritical failures that typically prevent Mango from continuing.

Log4j2 Category Names​

Use these category names to target specific Mango subsystems:

CategorySubsystem
com.serotonin.m2m2All core Mango code (Serotonin packages)
com.infiniteautomation.mangoAll core Mango code (IA packages)
com.serotonin.m2m2.dbDatabase operations
com.serotonin.m2m2.emailEmail sending
com.serotonin.m2m2.i18nTranslation/internationalization
com.serotonin.m2m2.rtReal-time runtime (data sources, event detectors)
com.serotonin.m2m2.web.mvc.restREST API
com.serotonin.m2m2.rt.eventEvent detectors
com.serotonin.m2m2.rt.maintBackups and purges
com.serotonin.m2m2.rt.dataSourceCore data source code
com.serotonin.m2m2.rt.publishCore publisher code
com.serotonin.m2m2.rt.scriptJava scripting engine
com.serotonin.ma.bacnetBACnet module
com.serotonin.bacnet4jBACnet protocol library
com.serotonin.m2m2.snmpSNMP module
org.snmp4jSNMP protocol library

Using Mango Properties in Log4j2​

You can reference mango.properties values in the log4j2.xml file using the syntax ${mango:property.name}. For example:

<PatternLayout pattern="${mango:appender.stdout.pattern}"/>

This allows the logging configuration to adapt based on your Mango environment settings without hardcoding paths or patterns.

Full Configuration Example​

A complete log4j2.xml file with rolling log files, corruption detection, and script logging is shown below. This is the default configuration that ships with Mango:

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration packages="com.serotonin.m2m2.rt.console">
    <Appenders>
        <Console name="stdout" target="SYSTEM_OUT">
            <PatternLayout pattern="${mango:appender.stdout.pattern}"/>
        </Console>
        <RollingRandomAccessFile name="logfile"
            filePattern="${mango:paths.logs}/%d{MM-dd-yyyy}-%i.ma.log.gz"
            fileName="${mango:paths.logs}/ma.log">
            <PatternLayout pattern="${mango:appender.logfile.pattern}"/>
            <Policies>
                <OnStartupTriggeringPolicy />
                <TimeBasedTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="${mango:appender.logfile.size}"/>
            </Policies>
            <DefaultRolloverStrategy fileIndex="nomax">
                <Delete basePath="${mango:paths.logs}">
                    <IfFileName glob="*.ma.{log,log.gz}" />
                    <IfAny>
                        <IfLastModified age="${mango:appender.logfile.delete.age}" />
                        <IfAccumulatedFileSize exceeds="${mango:appender.logfile.delete.size}" />
                        <IfAccumulatedFileCount exceeds="${mango:appender.logfile.delete.count}" />
                    </IfAny>
                </Delete>
            </DefaultRolloverStrategy>
        </RollingRandomAccessFile>
    </Appenders>
    <Loggers>
        <!-- Add your custom debug loggers here -->
        <AsyncLogger name="com.serotonin.m2m2"
            includeLocation="${mango:logger.mango.includeLocation}"
            level="${mango:logger.mango.level}"/>
        <AsyncLogger name="com.infiniteautomation"
            includeLocation="${mango:logger.mango.includeLocation}"
            level="${mango:logger.mango.level}"/>
        <AsyncRoot includeLocation="${mango:logger.root.includeLocation}"
            level="${mango:logger.root.level}">
            <AppenderRef ref="logfile" level="${mango:appender.logfile.level}" />
            <AppenderRef ref="stdout" level="${mango:appender.stdout.level}" />
        </AsyncRoot>
    </Loggers>
</Configuration>

Common Issues​

Log4j2 File in Wrong Directory​

If debug logging does not appear after making changes, verify that log4j2.xml is in the correct directory. Open mango.properties and check the paths.data entry. If empty, the path is relative to paths.home. If that is also empty, the file should be placed in the Mango root directory (MA_HOME).

Log Files Growing Too Large​

Debug logging can generate very large log files. Always use the most specific category possible (e.g., com.serotonin.m2m2.snmp instead of com.serotonin.m2m2) and remember to revert to info level when debugging is complete.