Mango Troubleshooting Methodology: Step-by-Step Triage Guide

Overview

When something goes wrong in Mango by Radix IoT, a systematic approach saves hours of guesswork. Jumping straight to "restart the service" or "call support" often wastes time and masks the real problem. This guide provides a repeatable 8-step methodology for diagnosing any Mango issue.

The value of working in order is that each step narrows the scope of the next one, and every step produces evidence you can hand to someone else. Resist the urge to jump to a remedy — particularly a resource-sizing one — before the evidence points there.

Prerequisites

A superadmin account. System status — where the health metrics, the Logging console and the Audit trail live — is restricted to superadmin, and there is no read-only way in
Access to ma.log, through the UI or on the filesystem
Network access from the Mango host to the devices involved, for connectivity testing
Somewhere to write findings down — a ticket or runbook entry — before you start changing things
Agreement on what "fixed" means for this incident, so you know when to stop

Finding System status, ma.log and the Audit trail

Several steps below use System status, and neither it nor any of its sections appears in the main menu. The only way in is through Admin home:

Open Administration → Admin home.
On the Server status card, click More details in the card's header.
System status opens with nothing selected. Pick a section under Choose a section — a list on the left of a wide screen, a drop-down on a narrow one.

Step	Section	What it gives you
2 — System health	Internal metrics	A name and value for each of Mango's internal monitors, with Refresh table
3 — Data sources	Data Sources Performance	Poll statistics per data source — read the caution in Step 3 first
5 — Logs	Logging console	View current ma.log, and a table of every log file with Download log on each row
6 — Changes	Audit trail	Every recorded configuration change, filterable by alarm level, change type, type, user and date

The 8-Step Triage Framework

Observe — what exactly is the symptom?
Check System Health — is Mango itself healthy?
Check Data Source Status — is the data source running and polling on time?
Check Data Point Status — are individual points updating?
Review ma.log — what errors are logged?
Check the Audit trail — did someone change something?
Use Diagnostic Tools — network, protocol-specific tests
Fix, Verify, Document

Work through these steps in order. Each one either identifies the cause or eliminates a class of causes, so even a step that finds nothing has narrowed the problem.

Step 1: Observe the Symptom

Start by asking precise questions rather than accepting "it's broken":

Which dashboard or screen shows the problem?
Which data points are affected?
When did it start? Was it working earlier today?
Is it all users or one user?
All points or specific ones?
All sites or one site?

Narrowing scope determines where to look. One user affected = likely permissions. All points on one device stale = likely network/device. Everything slow = likely system resources.

Step 2: Check System Health

Start on Admin home: the Server status card shows System uptime directly. For everything else, click More details and open Internal metrics, which lists JVM memory, thread counts, work queue depths and database connection counts.

JVM heap: JVM used memory (MB) against JVM maximum available memory (MB) — but read it as a trend, not a single number. See the note below.
Thread count: compare against this system's own normal. A count that climbs and never comes back down is worth investigating; a count that is simply higher than someone else's system is not.
Work queues: Mango reports running and queued counts for the high, medium, and low priority queues. A queue that drains is doing its job; a queued count that grows steadily means work is arriving faster than it is being completed. In Mango 5.7.4 the low priority pair is wrong: Low priority tasks queued never receives a value, and Low priority tasks currently running actually reports the queue depth. Read the high and medium queues.
Database connections: Active database connections versus Idle database connections for the main pool, and the same pair for the read-only pool. Sustained saturation of a pool points at the database rather than at Mango.
Uptime: short uptime you did not expect means the process restarted. Find out why before investigating anything else.

Warning

High heap usage is a reason to investigate, not a reason to resize. A JVM is expected to fill its heap and then collect; an instantaneous reading near the top of the heap is normal behaviour, not evidence of a problem. What tells you something is a plot of used heap after garbage collection over time. If post-GC usage returns to a stable baseline, the heap is doing its job however high the peaks are. If post-GC usage trends upward run after run, something is retaining memory and a larger heap will only postpone the symptom. Before changing -Xmx, look at GC frequency and pause times — GC logging is off by default and writes to standard output rather than ma.log, so it has to be switched on first — along with CPU, the work queues above, database latency, polling load, and query volume. Remember that a larger heap can mean longer pauses.

Tip

Add an Internal Data Source to track JVM metrics as data points. Then trend memory usage over time on a dashboard — which is what turns a single reading into the post-GC trend you actually need.

Step 3: Check Data Source Status

Open the suspect data source and go to its Runtime status tab. Current state shows whether it is running; Latest poll times lists its last ten polls with Poll start time, Poll duration and Poll aborted; and Latest aborted poll times lists the last ten aborts, or reads No aborted polls.

Enabled: a disabled data source polls nothing, so every one of its points goes stale at once.
Poll success percentage: the share of this source's scheduled polls that were not aborted, counted since the data source last started. A poll counts as successful as soon as it starts on time, before it talks to the device, so device timeouts and errors do not lower it; those show under Connection errors below. Anything below 100% means polls have been aborted. Because the figure is cumulative, a long-running source moves slowly, so read Latest aborted poll times for recent trouble.
Poll duration vs update period: a poll that runs long still completes, but it delays the ones behind it. A poll that cannot start within one whole update period of its scheduled time is skipped and counted as aborted. The first abort after the data source starts raises a Poll aborted event — Urgent by default — and later aborts raise nothing more until the source is restarted, so Latest aborted poll times is where to see whether aborts are continuing. Either lengthen the update period or reduce the work in each poll. A source scheduled with Use cron is never marked aborted for lateness, so its polls can fall behind without that event.
Connection errors: read the actual error text rather than mapping symptoms to causes. A timeout is consistent with an unreachable device, a busy device, a firewall dropping traffic, or a too-short timeout setting; a refused connection is consistent with the wrong port, a service that is down, or a host-based access rule. Confirm which with Step 7.
Multiple slow sources: if several data sources degrade at the same time, that is a reason to look for a shared cause — the host, the network path, or the database — before investigating any one source.

To compare sources side by side, open the Data Sources Performance section of System status. It shows Previous Consecutive polls, Poll duration (ms) and Successful Polls (%) for each source — but it builds that table from data points created by an Internal Data Source, so on an instance without one it shows an empty table, which looks exactly like "no problems".

Step 4: Check Data Point Status

Is each suspect point enabled? A disabled point shows Disabled where its value would be.
What is its current value, and when did it last update?
Has the data source flagged the value as unreliable? Mango shows a warning icon beside the value, with the tooltip Point unreliable.

Pattern recognition: All points stale on a data source → data source or network issue. Only some points stale → point-level config issue (wrong register, wrong data type, disabled point).

Step 5: Using ma.log for Diagnostics

The ma.log file is your most powerful diagnostic tool. On a default install it is at:

{mango-install-dir}/logs/ma.log

If paths.data or paths.logs is set in mango.properties, it moves with them. From the UI, click More details on Admin home's Server status card and open Logging console: View current ma.log opens it in the page, and Download log on any row of the file table saves a copy.

Every restart starts a fresh ma.log. Earlier entries are in the rotated files — dated and gzipped, named like 09-23-2026-1.ma.log.gz — in the same folder and the same table. If the incident began before the last restart, the evidence is in one of those.

What to look for:

ERROR level: Connection failures, OutOfMemoryError, database errors, module failures
WARN level: including aborted polls — "Data Source … aborted … polls since it started." That line is written at most once an hour per source and its count is cumulative since the source started, so a quiet log is not evidence the aborts have stopped.
Filter by timestamp: each line starts with the level and then an ISO-8601 timestamp, so narrow to the incident window first
Search keywords: Data source name, "Exception", "timeout", device IP address

Step 6: Using the Audit trail

Open Administration → Admin home, click More details on the Server status card, then choose Audit trail. It is not in the main menu on any configuration. Switch on Date filter to limit the list to the page's date range around when the issue started, and narrow further by Change type (Create, Modify, Delete), Type, or user. Look for changes to:

Data sources (address, credentials, update period, enabled state)
Data points (enabled state, data type, logging)
Event detectors and event handlers — a changed or deleted one is a common reason an alarm stops arriving
System settings
Users and roles

Click a row to see each property that changed, with its old and new value. If the issue start time correlates with a configuration change, you've likely found root cause.

Step 7: Diagnostic Tools

When Mango-level checks are inconclusive, use external tools:

Network: ping, traceroute, telnet {ip} {port} to verify connectivity
Protocol-specific: Standalone Modbus client, BACnet discovery tool, snmpwalk for SNMP
REST API: Query point values directly to determine if the issue is in Mango or the dashboard layer

Simple API check — the most recent stored value of one point:

GET /rest/latest/point-values/latest/{xid}?limit=1

If the API returns current data but the dashboard shows stale data, the issue is in the dashboard layer (widget config, permissions, browser cache) — not in data collection. This call returns logged values, so check the point's logging type before reading an old timestamp as a collection failure: a point logged When point value changes keeps its last timestamp for as long as the value holds steady, even while polling is healthy.

Step 8: Fix, Verify, Document

Plan the fix — what will you change and why?
Apply the fix
Verify immediately — is the specific symptom resolved?
Monitor for regression — watch for a reasonable period
Check adjacent systems — did the fix introduce side effects?

Warning

Change one thing at a time. Multiple simultaneous changes make it impossible to know which one fixed it.

Document the resolution: Record symptom, root cause, fix, and prevention. Keep a runbook your team can reference.

Putting It All Together: Example Triage

Reported: "Dashboard shows stale data — temperatures haven't updated in 2 hours."

Observe: Building A temperature points, stale since 10:15 AM
System Health: Heap OK, no queue backlog, uptime 45 days → system healthy
Data Source: Modbus source for Building A — last poll 2 hours ago, "Connection timed out"
Isolate: Ping device — no response. Device unreachable.
Root cause: Network switch failure in building IDF closet
Fix: Network team replaces switch
Validate: Mango resumes polling automatically. Data current within one poll cycle.
Document: Log incident, root cause, and resolution in team runbook

Verification

Before closing an incident, confirm all of the following:

☐ The specific reported symptom is gone, checked the same way the reporter checked it
☐ The evidence supports the cause you have written down — you can point at the log entry, audit record, or test result, not just a plausible story
☐ Only one thing was changed, or each change was applied and verified separately
☐ Data is flowing again for every affected point, not just the one you were watching
☐ Internal metrics are back to this system's normal range, and heap has been checked as a post-GC trend rather than a single reading
☐ ma.log shows no new errors since the fix
☐ Adjacent systems and dashboards still behave correctly
☐ The symptom, evidence, cause, fix, and any remaining uncertainty are recorded in the runbook
☐ If the cause is unconfirmed, that is stated explicitly rather than implied to be resolved

Troubleshooting the Triage Itself

Situation	What is usually going wrong	What to do
You cannot reproduce the symptom	Scope was never narrowed — user, page, point, device, and time window are still unknown	Go back to Step 1 and get a specific, repeatable observation before changing anything
The fix worked but you cannot say why	Several changes were applied together, or a restart masked the cause	Record it as unresolved-but-mitigated and keep monitoring. A restart that fixes something is evidence, not a diagnosis
The problem returns after a while	A symptom was treated rather than a cause — classically, resizing the heap for a retention problem	Return to Step 2 with trend data across the whole period rather than a snapshot
Every metric looks fine but users still report a problem	The issue is above the data layer — dashboard configuration, permissions, browser state, or the time range being queried	Use the REST check in Step 7 to establish whether data collection or presentation is at fault
Data is missing for a past period	Logging, connectivity, time range, or retention — not a query problem	Check the point's logging configuration, source health for that period, the query range, and whether purge has removed it. Rollups summarise data that exists; they do not reconstruct data that does not
Triage stalls with no clear next step	Evidence gathered so far has not been written down and compared	Write out what each step ruled in and ruled out, then escalate with that summary rather than with the symptom alone

Summary

Effective troubleshooting follows the 8-step framework: Observe, System Health, Data Source, Data Point, Logs, Audit trail, Diagnostic Tools, Fix and Document. Working in order means every step either finds the cause or eliminates a class of causes, and it keeps you from applying a remedy — especially a resource-sizing one — before the evidence points at it.

Tip

A simplified 5-step version works well for quick triage: (1) Observe the symptom precisely, (2) Reproduce it — if you can’t reproduce it, you can’t confirm you fixed it, (3) Isolate it to a specific user, page, data source, or device, (4) Identify the cause from evidence, checking the cheapest things to rule out first — configuration and permissions cost seconds to check, network and hardware cost longer — and (5) Fix, validate, and document. Checking cheap explanations first is about the cost of the check, not a claim about which causes are most common on your system; your own incident history is the only reliable guide to that.