How to Use Mango Logs for Troubleshooting

Overview

When something goes wrong in Mango by Radix IoT, the log files are your primary diagnostic tool. They record startup events, errors, warnings, script output, and system messages. Knowing where to look and what to search for turns a vague "something's broken" into a specific, fixable problem.

Log File Locations

Every log file lives in one directory, set by paths.logs in mango.properties. It defaults to logs, relative to Mango's data directory.

Log Levels

What is on by default. Mango's own packages (com.serotonin.m2m2, com.infiniteautomation, com.radixiot) log at INFO; everything else — libraries, the web server, the database driver — logs at WARN. So an absent INFO line from a third-party library is normal, not evidence that nothing happened.

Common Search Patterns

Startup Problems

Search for these patterns when Mango won't start or starts with errors:

• ERROR + startup — errors during initialization
• OutOfMemoryError — JVM ran out of memory
• Address already in use — another process is using Mango's port
• database + ERROR — database connection failures
• module + ERROR — module loading failures

Communication Errors

Search for these when data sources stop collecting data:

• Connection refused — device or service not listening on expected port
• Connection timed out — network can't reach the device
• SocketException — network connection dropped
• ModbusTransportException — Modbus-specific communication failure
• Data source XID or name — filter to see errors for one specific source

Script Errors

Search for these when scripts aren't working — and search the script's own log, not ma.log. The scripting loggers are set to write elsewhere, so a script error will not appear in ma.log at all:

• ScriptError or ScriptException — JavaScript execution failure
• ReferenceError — script references an undefined variable
• TypeError — script tries to call a method on null or wrong type
• The script's name or XID — filter to one script's output

Performance Issues

• aborted — a polling data source logs "Data Source X aborted N polls since it started" at WARN when it cannot keep up. Note it is written at most once an hour per source, so one line can stand for an hour of aborts
• pool exhausted or thread pool — system is overloaded
• timeout — operations taking too long

Do not search ma.log for garbage collection. GC logging is off by default and would not go there anyway — the JVM writes it to stdout. To turn it on, uncomment the -verbose:gc -XX:+PrintGCDetails line in start-options.sh and restart. For memory pressure without touching JVM flags, read the JVM memory monitors in Internal metrics instead — open Administration → Admin home, click More details on the Server status card, and choose Internal metrics under Choose a section.

Reading Log Entries

The layout is set by appender.logfile.pattern in mango.properties, which ships as %-5p %d{ISO8601} (%C.%M:%L) - %m%n. The level comes first, not the timestamp:

ERROR 2024-03-15T14:23:45,123 (com.serotonin.m2m2.modbus.rt.ModbusDataSourceRT.doPoll:214) -
  Error reading Modbus device at 192.168.1.100:502 -
  Connection timed out after 5000ms

Breaking it down:

• Level: ERROR — severity, padded to five characters and printed first
• Timestamp: 2024-03-15T14:23:45,123 — ISO 8601, so the date and time are joined by a T
• Origin: (com.serotonin.m2m2.modbus.rt.ModbusDataSourceRT.doPoll:214) — in parentheses, and it is more than a component: the full class name, the method, and the line number. That line number is often the fastest route to the cause
• Message: The specific error with details (IP address, timeout duration)

The origin field is there because logger.mango.includeLocation is true. It is what makes searching by class name — EventHandlerRT, ModbusDataSourceRT — work at all. script.log uses a different pattern with no location field.

Changing Log Levels

Edit mango.properties, not log4j2.xml. Mango ships a fixed log4j2.xml inside its Core resources and feeds it values from mango.properties; editing the shipped file is not the supported route and an upgrade will replace it.

1. Open mango.properties and find the logging block
2. Set the level for the scope you need:
   • logger.mango.level — Mango's own code, info by default. This is the one you usually want at debug
   • logger.root.level — everything else, warn by default
   • logger.script.level — scripting, already trace
3. Restart Mango. The shipped configuration sets no monitorInterval, so log4j2 does not watch the file and the change will not be picked up while Mango is running
4. Important: Set it back afterwards. DEBUG on logger.mango.level generates a very large amount of output and will roll ma.log over quickly, pushing the entries you wanted into gzipped archives

One package at a time is not available from mango.properties. The shipped configuration names its loggers up front, so the three levels above are the only scopes it exposes. To turn up a single package, point log4j2.configurationFile at your own log4j2.xml — the path is relative to Mango's data directory unless it is absolute.

Log Rotation

Mango rotates logs automatically, and it does not use the numbered-suffix scheme people expect.

• ma.log is always the current file
• A rotated file is gzipped and named by date: MM-dd-yyyy-N.ma.log.gz, where N counts the rotations within that day. There is no ma.log.1
• Three things trigger a rotation, not one: Mango starting up, the date changing, and the file reaching appender.logfile.size (100 MB by default). The startup trigger is why a restart always begins a fresh ma.log
• Old files are deleted when any of three limits is exceeded: older than appender.logfile.delete.age (30 days), more than appender.logfile.delete.count files (1000), or more than appender.logfile.delete.size in total (1 GB)
• Looking for yesterday's event means opening yesterday's .gz, and decompressing it first

Practical Troubleshooting Workflow

1. Note the time when the problem occurred (or was first reported)
2. Open ma.log — the fastest route is the Logging console, which lists every log file with a download button and a View current ma.log shortcut. System status is not in the navigation menu: it is superadmin-only and hidden, so reach it from Admin home → the Server status card → More details, then pick Logging console from the section list. Search for ERROR entries around that time
3. Look for context — the lines before and after the error often explain the cause
4. Search for the data source or point XID if the issue is specific to one device
5. Check for patterns — does the error repeat at regular intervals? Does it correlate with other events?
6. Enable DEBUG temporarily if the ERROR messages don't give enough detail — logger.mango.level=debug in mango.properties, then restart

Log Analysis Tips

• Correlate with events — if an alarm fired at 2:15 PM, check the log around that time
• Count error frequency — one timeout per day is different from 100 per hour
• Look for cascading failures — one database error can cause dozens of downstream errors. Fix the root cause
• Include logs in support requests — when contacting Radix IoT support, include the relevant log excerpts. They speed up diagnosis significantly

Summary

The ma.log file is your best friend for troubleshooting, and the Logging console is the fastest way to reach it. Start with ERROR entries around the time of the issue, search by class name or by data source name, and look for patterns. Remember that script output lives in its own files, that rotated logs are gzipped and named by date rather than numbered, and that raising a log level means editing mango.properties and restarting. Set it back afterwards. When contacting support, include relevant log excerpts for faster resolution.