Home › Topics › Visualizing Network Health: Maps, Weathermaps, and Heatmaps › Keeping Maps Truthful

Keeping Maps Truthful: Stale Data, Green by Default, and Maps That Lie


A map is a claim. Every green box says "this device is fine right now." Every thin pale line says "this link is quiet." And every empty space says "there is nothing here worth drawing." The trouble is that a map goes on making those claims after it has stopped being able to back them up. It makes them in exactly the same colours it used when they were true. A dead map and a healthy network look identical from the doorway.


I have never seen a map that was deliberately wrong. I have seen dozens that drifted. A collector stopped, a switch was added, a circuit was upgraded, and a dependency was set backwards. And the map kept smiling through all of it. None of those things is a failure of the map. They are the ordinary life of a network. And a map that has no way to notice them will lie by accident, which is the only way maps ever lie.


By the end of this guide you will be able to name the seven ways a map deceives. You will be able to put a freshness indicator and an unknown state on every map you own. You will be able to run a monthly truthfulness check from a checklist you can copy. You will be able to find the devices that are monitored but drawn nowhere with a short query. And you will be able to apply the one ownership rule that keeps all of it happening. There is also a story about nine quiet days.


In this guide

  • The seven ways a map lies
  • The freshness indicator and the unknown state
  • The monthly truthfulness check
  • Finding the unmapped device
  • The ownership rule
  • A war story: nine quiet days
  • The truthfulness checklist
  • Where to go next

The seven ways a map lies


Maps lie in predictable ways, and predictable is good news, because each one has a tell and a fix. Here are the seven I check for, in the order I have been burned by them.


1. Green by default

The map paints a device green unless it has been told otherwise. So a device that has never been polled, or has not been polled lately, looks healthy. This is the root of most of the others. The map has two colours in mind, "up" and "down," and it has no word for "I do not know." So it says "up." The fix is a third answer, unknown, painted a colour that is not green. The fix also includes a rule that puts every device into that state until fresh evidence takes it out.


2. The dead collector

The collector is the part of the monitoring system that does the polling: the central service, or a remote probe at a branch. When it stops, nothing it watched is polled, and every device it watched freezes at its last known state. If that state was green, the map stays green until someone notices, and nobody notices, because green is what they were hoping for. Monitoring system failure modes catalogues the ways a collector dies; the map's job is to show the death, not hide it.


3. The unmapped device

A device that was added to the network and never to the map is not red and not grey. It is absent, and absence looks like "nothing to see here." This is the quietest lie of the seven, because the map is not wrong about anything it shows. It is wrong about what it leaves out. The new core switch that went in during the last refresh can fail without a single pixel changing.


4. The out-of-date link

Links get upgraded, moved, and removed, and the map finds out last. A line still drawn between two switches that no longer connect will stay green forever, because nothing polls a line. It inherits its colour from the interfaces at its ends. Those interfaces may now be doing something else entirely. A removed link that stays on the map is an outage that can never be shown.


5. The wrong dependency

A dependency tells the monitoring system that one device is reachable only through another. That means when the parent fails the children are marked unreachable rather than down. Set correctly, it turns forty red boxes into one. Set wrongly, it lies in one of two directions. A missing dependency paints a whole site red for one failed router. A backwards one hides a genuinely dead device behind a parent that is fine, grey and unalarming. Dependency thinking covers how to get the chain right, and the status map guide shows how the map should paint it.


6. The wrong speed on a weathermap

A weathermap colours each link by traffic divided by capacity. If the capacity is wrong the colour is wrong by the same factor, in either direction. A one-gigabit circuit drawn as ten gigabits shows eighty percent as eight. The counter is correct, the map is confident, and nothing on the screen suggests otherwise.


7. The map nobody owns

All six of the above are caught by a person looking at the map on purpose, with a list, once a month. A map with no owner is a map nobody looks at on purpose. So every one of the other lies accumulates until the day the map is needed. That is the day it is least likely to be true. This lie is the cause of the others, and its fix is the shortest: a name and a date.


The lieWhat you seeThe tellThe fix
Green by defaultA device that has never reported looks healthyNo last-poll time on the nodeUnknown state until first successful poll
Dead collectorA whole site or the whole map frozen greenEvery node's last-poll time is the same, and oldStale rule, probe as a dependency, heartbeat
Unmapped deviceNothing; the device is absentMonitored device list longer than mapped listMonthly comparison query
Out-of-date linkA green line between things no longer connectedInterface description does not match the far endLink inventory review
Wrong dependencyA red site, or a grey box hiding a dead deviceAlert storm, or an outage with no alertWalk the chain against the topology
Wrong speedA calm link that users say is slowInventory speed differs from device or contractQuarterly speed check
No ownerAll of the above, over timeNo name or date on the mapName and review date on every map

The freshness indicator and the unknown state


Two features on the map itself catch the first two lies before a human has to. The first is a freshness indicator: a timestamp, on the map as a whole and on each node, showing when the data behind it was last refreshed. The second is the unknown state as a first-class colour, painted automatically when a node's timestamp gets old.


The map-level timestamp is the one the room reads. It sits in a corner, large enough to read from wherever the map is read, and it shows the time of the last repaint. If that time is more than two poll intervals in the past, the map should say so loudly. In that case, use a grey wash over the whole thing, or a banner that reads "no update since 14:05." A map whose page has stopped refreshing is a screenshot, and a screenshot on a wall is a promise nobody is keeping.


The per-node timestamp is the one the engineer reads, on hover or click, and it drives the unknown state. The rule is simple: after N missed polls, the node goes grey. I use three. With a five-minute poll, a node goes grey fifteen minutes after its last successful reading. That is quick enough to catch a dead probe before lunch and slow enough not to flicker on one dropped packet. Write the number in the legend, in minutes, so "stale" has a definition.


The unknown state must look different from up, from across the room, and it must mean exactly one thing: no current evidence. Not "warning," not "minor," not "probably fine." A dashed outline and a white fill work; so does a small "?" badge. The mistake to avoid is a grey so pale it reads as green from three metres, which is the mistake I made first. (A colleague asked why the map had "a slightly sad site" on it. The site had been unpolled for two days.)


Tip: the freshest-looking lie is the map that refreshes its page every ten seconds from data that stopped changing an hour ago. The page timestamp updates, the node timestamps do not. Show both, and make the node timestamps the ones that drive the colour.


The monthly truthfulness check


Once a month, somebody with a name sits down with the map and this list. It takes about an hour for a map of a few dozen nodes. And it catches every lie in the table above except the ones the freshness indicator already caught. Copy it as it stands; it is deliberately plain.


  1. Compare the map's device list to your inventory. Export the list of devices drawn on the map and the list of devices the monitoring system polls. Compare both against your inventory of what is actually installed. Every device in the inventory should be monitored; every monitored device in the map's scope should be drawn. Record each gap and who will close it.
  2. Pull one node's cable in a test window. Choose a non-critical access switch, open a maintenance window for it, disconnect its uplink, and watch the map. Within one poll interval the node should go red, its children should go grey, and nothing else should change. Reconnect and watch it recover. Note the time from cable out to colour change.
  3. Confirm the link speeds. For each link on any weathermap, compare the inventory speed against what the device reports and, for rented circuits, against the contract. Correct the inventory, then the map, and note the source of each number.
  4. Confirm the collector heartbeat. Check that the central service and every remote probe has a heartbeat check that fires when it stops. Check that the last heartbeat is recent. Stop one probe deliberately, confirm the heartbeat alert arrives, and confirm its devices go grey on the map.
  5. Walk one dependency chain. Pick a branch and trace every device's parent back to the core. Each parent should be the device the traffic actually passes through, and the probe should be a parent of everything it polls.
  6. Read the legend. Confirm every colour in use on the map appears in the legend. Confirm the stale threshold is stated in minutes, and the poll interval is stated.
  7. Update the review date. Write today's date and your name on the map, and the date of the next check.

Step one is the same comparison coverage reviews describe for the monitoring system as a whole. The map check is that review narrowed to one picture. Step two is the only one that costs anything, and it is the one people skip. A map that has never been tested by an outage it was told about in advance has never been tested. Suppress the alert for the test switch by all means, but check how your tool paints a suppressed device. Some paint it a maintenance colour, which is fine as long as the children still go grey.


Step four is where the dead-collector lie is caught before it happens. A heartbeat is a check that expects a signal on a schedule and alarms when the signal stops. That is the only way to notice that the thing that notices things has stopped noticing. Heartbeats and dead-man switches covers how to build one; the map check only confirms it is still there.


Finding the unmapped device


The unmapped device is the lie a query catches better than an eye. The monitoring system holds a table of devices it polls, and the map holds a list of nodes it draws. A device in the first and not the second is monitored and invisible. Exactly how those two lists are stored varies by product, so the query below is illustrative. It shows the shape, and the table and column names will be different in yours. Check the product documentation for where map membership lives.


-- Illustrative only: table and column names vary by product.
-- Devices that are polled but do not appear on any map.
SELECT d.name, d.ip_address
FROM devices d
LEFT JOIN map_nodes m ON m.device_id = d.id
WHERE m.device_id IS NULL
  AND d.enabled = 1
ORDER BY d.name;

If you cannot query the database, two exports and a comparison do the same job. Export the monitored device names to one CSV file and the mapped node names to another, then compare them. In PowerShell, on the Windows machine that runs the monitoring service:


$monitored = Import-Csv monitored.csv | Select-Object -ExpandProperty name
$mapped    = Import-Csv mapped.csv    | Select-Object -ExpandProperty name
Compare-Object $monitored $mapped | Where-Object SideIndicator -eq '<='

The rows that come back are monitored and not drawn. Run the comparison the other way (the => side) and you get the opposite list. These are nodes on the map that no longer exist in monitoring. They are the ghosts of decommissioned devices, still green, still reassuring. Both lists should be empty after the monthly check. The first month they never are.


The comparison has a blind spot of its own: it finds devices that are monitored and not mapped. And it cannot find devices that are installed and not monitored, because neither list knows about them. That is what the inventory in step one is for. And it is the reason the inventory has to be something other than the monitoring system's own device list. Auto-discovery narrows the gap, since a tool that scans the network for new devices will find the switch someone racked on Friday. But it finds it as a monitored device, not as a mapped one. The map still has to be told.


The ownership rule


Every map has a name on it and a review date, or it does not go on a wall. The name is the person who runs the monthly check. The date is when they last did, and beside it, when they will next. Both are written on the map itself, in the corner opposite the timestamp, where anyone reading the map can see them.


The rule sounds bureaucratic and is the opposite. A map with a name on it is a map someone will defend, correct, and eventually retire. A map without one is a map everyone assumes someone else is watching. The name also answers the question the on-call engineer asks at two in the morning: "can I trust this?" The name comes with a date that says how recently someone checked. Documentation that survives makes the same argument for the static diagram, and it is the same argument.


Ownership includes the right to delete. A map whose owner leaves, and whose review date passes twice without a new name, comes off the wall. That is not a punishment; it is the only way to stop the map nobody owns from becoming the map everybody trusts. Dashboard maintenance burden puts a cost on every screen that stays up, and a map is a screen.


A war story: nine quiet days


Ashgrove Housing's monitoring service stopped on a Friday evening after a patch reboot left the Windows service disabled. The wall map in the IT office showed every one of its ninety devices green for the following nine days. Nobody noticed, because the map looked exactly as it did on every good day. The page kept refreshing, so the clock in the corner kept moving. On the ninth day a distribution switch failed. Forty users lost the file server. The first indication was a phone call. That was followed by a second phone call asking why the map still said everything was fine. The post-incident review recorded that the monitoring system had been "unavailable for a period," which was one way of describing nine days. The fixes were a heartbeat on the service and a per-node stale rule that turned the map grey after fifteen minutes of silence. There was also a page timestamp driven by the data rather than the browser.


The story has no villain, which is what makes it worth telling. A service stopped, as services do, and a map did what an untended map does, which is nothing. The nine days were not a failure of monitoring. They were a failure of the map to say "I have not heard anything," and that sentence is the whole subject of this guide.


The truthfulness checklist


This is the short version, for the map you inherited or the one you are about to hang. Every line is a yes or a no.


  • The map shows a timestamp of its last data refresh, readable from where the map is read.
  • Each node has a last-poll time, visible on hover.
  • A node goes to an unknown colour after a stated number of missed polls, and the number is in the legend.
  • Unknown looks different from up at three metres.
  • Every collector and probe has a heartbeat check, and its devices depend on it.
  • Every device the monitoring system polls, within the map's scope, is drawn on the map.
  • No node on the map refers to a device that no longer exists.
  • Every link on the map connects two interfaces that are actually connected.
  • Every weathermap link speed has a recorded source.
  • Every device has a dependency parent, and the chain has been walked in the last quarter.
  • The map has been tested with a real disconnection in a test window.
  • The map carries an owner's name, the last review date, and the next.

Where to go next


A truthful map is not one that is never wrong. It is one that says when it does not know. The freshness indicator and the unknown state let it say that on its own. The monthly check and the comparison query catch what it cannot see. The ownership rule makes sure somebody is there to run them. Everything else in this pillar builds the pictures. This guide is what keeps them worth looking at.


If you are starting from nothing, choosing the right picture decides which map to build. And heatmaps for time and scale covers the grid that takes over when a map runs out of room. The same freshness rules apply to the wall dashboards in the sister pillar on dashboard design. All of these guides live under Visualizing Network Health: Maps, Weathermaps, and Heatmaps.


Put this into practice with SysPeep Monitor

Most of the lies in this guide come from a map that is drawn separately from the polling behind it. SysPeep Monitor draws its network maps and live dashboards from the same central Windows service and remote probes that do the polling. It applies the dependencies you set so a parent failure does not flood the map with red. It auto-discovers new devices and interfaces so the unmapped switch at least shows up as a monitored one. The free trial installs in an afternoon.

Download Free TrialLearn About SysPeep