🧩 Journey B: Start From the Beginning
Use this when a data issue has been reported but you don't yet know what's actually wrong. Work through the checkpoints below in order — each one narrows down where the fault is, and lists the likely causes at that layer so you can often identify the reason without leaving the step. Only move to the next checkpoint once the current one passes.
If you know exactly what's wrong (e.g. "a specific alert is firing," "device is offline"), skip ahead to 🎯 Journey A: Symptom Lookup instead — it's faster.
See the 📘 Monitoring Tools Reference for what each tool referenced below shows and where to find it.
🗺️ The Funnel
1️⃣ Checkpoint: Connectivity
Question: Is the device online right now, and has it been reliably reachable?
Check: Open the 🌐 Offline Dashboard for the device.
- 🟢 Online → connectivity is fine, go to Checkpoint 2: Data Arrival.
- 🔴 Offline → stay here and diagnose using the causes below.
Likely causes at this checkpoint
Open 📈 Uptime Metrics for the device and look at the drop pattern — it tells you which cause is most likely:
| Pattern in Uptime Metrics | Likely cause | Confirm with |
|---|---|---|
| 🔴 Hard drop to 0%, no recovery | Power supply failure, or device physically damaged | 📶 IoT Telemetry — completely silent (no reconnect attempts) confirms power/hardware. Power supply failure and stops measuring / Device damage |
| 🟠 Drops at the same time of day, recurring | Power/network scheduling issue (e.g. solar/battery source, congestion window) | Compare against other devices on the same power/network source |
| 🟡 Random intermittent flapping | Weak signal, unstable communication cable/connector | 📶 IoT Telemetry — device is trying to reconnect but failing. Communication cable gets damaged |
| 🔵 Multiple devices in the same zone dropped together | Shared site-wide network/power outage, not a per-device fault | 🌐 Offline Dashboard filtered by zone/site |
| ⚪ Went offline right after a service/replacement visit | Improper re-configuration, or device left unpowered after service | 📝 User Logs (unit level) — check the service timestamp |
| 💳 Went offline around a recharge/payment due date | Recharge or payment lapse (not a technical fault) | 📝 User Logs (industry level) — see Checkpoint 4: Billing |
Once you've matched a pattern above, follow that factor's linked debug steps to confirm and resolve. If none of the patterns match, or the device recovers and drops again unpredictably, escalate to the field team with the Uptime Metrics history attached.
2️⃣ Checkpoint: Data Arrival
Question: Now that the device is online, is it actually sending data every 5 minutes as expected?
Check: Open 📶 IoT Telemetry for the device ID.
- 🟢 Data arriving on schedule → go to Checkpoint 3: Data Correctness.
- 🔴 Data NOT arriving on schedule, despite being "online" → this is unusual (device shows connected but isn't transmitting) — treat as a connectivity fault and go back to Checkpoint 1 causes, prioritizing the intermittent/weak-signal row.
Likely causes at this checkpoint
- Device is connected to the network but the meter/sensor itself isn't reporting → see Sensor gets damaged and stops measuring in between.
- Communication link between sensor and IoT unit is faulty (device is online, sensor isn't heard) → see Communication cable gets damaged.
3️⃣ Checkpoint: Data Correctness
Question: Data is arriving — but is it correct, and is it reflected properly on the dashboard?
This checkpoint has two independent things to check: the values themselves, and whether they're reaching the dashboard correctly.
3a. Are the values themselves suspicious?
Check: Open 🚨 Data Integrity Alerts for the device/unit.
| Active alert | Likely cause | Go to |
|---|---|---|
🔴 device_status | No data received — power or RS485 communication issue | Communication cable gets damaged / Power supply failure and stops measuring |
🟠 no_flow | Flow meter fault, closed valve, blocked line, bad installation | Flow meter starts counting false water flow / Follow the right installation practices |
🟡 no_level_variation | Level sensor stuck/damaged, miscalibrated, or tank genuinely unused | Follow the right installation practices / Selection of right sensor |
🔵 water_balance_leakage | Unaccounted water — real leakage, or a metering/config error | Flow meter starts counting false water flow |
| ⚪ Value pinned at a min/max boundary | Junk value or out-of-range reading | Junk values posted from the sensor / Data outside the permissible range |
If an alert is active, follow its linked page's How to verify steps and stop here.
3b. No alert active, but the dashboard still looks wrong?
This means the fault is downstream of the sensor/device — in how data is stored, processed, or displayed.
Check, in order:
- 🗄️ Data Validation — look at the recent raw data received into the database for this unit.
- Reverse flow flag is set → this is the most common cause of "data arrives but doesn't register." Confirm via the daily reverse-flow alert in Google Chat, then resolve from the 🔄 Unit Reset tab. See Reverse flow conditions.
- Device ID misconfigured (mismatch between physical device and its registered ID) → correct the registration.
- Data format looks off compared to other healthy units → likely a config or pipeline issue, see below.
- 📝 User Logs (unit level) — check for a recent re-configuration, replacement, or service activity. Misconfiguration after a service visit is a common cause here — see Improper re-configuration during replacement/service activities.
- Is this affecting many unrelated devices/zones at once, not just one unit? If yes, this points away from a single-device cause and toward a shared software/pipeline fault:
- Check whether the issue started right after a new deployment — compare the release timestamp against when the symptom started. See New deployment affects the real-time data pipeline.
- Check for an architecture-component outage (Storm topology restart, batch processing failure) in the same window. See Unexpected system downtime due to failure of any architecture component.
- Check 📝 User Logs (industry level) for a bulk configuration change applied around the same time.
- ✅ Cause identified and fixed (reverse flow reset, config corrected) → done.
- ⚠️ Still unresolved after checking all of the above → this is a genuine unknown — document what you've ruled out (see Documenting What You've Found) and escalate to engineering.
4️⃣ Checkpoint: Billing
Question: Is this actually a technical fault at all, or is the device/account simply not supposed to be active right now?
Check: This is usually the first thing to rule out if Checkpoint 1 showed the device went offline, since a recharge/payment lapse looks identical to a connectivity failure from the Offline Dashboard alone.
| Situation | Likely cause | Go to |
|---|---|---|
| Device offline, starting at/after the recharge due date | Recharge not completed on time | Devices go offline due to failed recharge on time |
| Whole account/site unreachable, not just one device | Payment failure causing a broader cloud-side outage for that account | Cloud system goes down due to payment failure on time |
| Offline started before the due date | Not billing-related — go back to Checkpoint 1 | — |
A confirmed recharge/payment lapse is expected system behavior, not a data reliability defect — don't file it as one.
📋 Documenting What You've Found
Once you've identified (or ruled out) a cause at any checkpoint, record it against the unit/incident:
- 🪜 Checkpoint where the fault was found (Connectivity / Data Arrival / Data Correctness / Billing).
- 🎯 Specific factor — use the naming from 🔧 Sensor Side, 📡 IoT, 💻 Software Issues, or 💳 Recharge Issues.
- 🔍 Evidence — which tool(s) confirmed it, with the relevant time window/screenshot reference.
- ✅ Resolution/action taken — e.g. unit reset, config corrected, hardware replaced, escalated to field team.
This keeps a traceable history in User Logs and helps identify recurring patterns across units over time — a checkpoint that keeps failing for the same unit is a signal to fix the root cause, not just clear the symptom again.