| 1 | <!--startmeta |
| 2 | custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/network-flows/visualization/maps-globe.md" |
| 3 | sidebar_label: "Maps and Globe" |
| 4 | learn_status: "Published" |
| 5 | learn_rel_path: "Network Flows/Visualization" |
| 6 | keywords: ['country map', 'state map', 'city map', 'globe', 'visualization'] |
| 7 | endmeta--> |
| 8 | |
| 9 | <!-- markdownlint-disable-file --> |
| 10 | |
| 11 | # Maps and Globe |
| 12 | |
| 13 | Four geographic views, all driven by the same aggregation engine as the Sankey and Time-Series: |
| 14 | |
| 15 | - **Country map** — countries connected by edges weighted by traffic |
| 16 | - **State map** — same, at state/province granularity |
| 17 | - **City map** — same, at city level (down to street-level granularity, depending on your GeoIP database) |
| 18 | - **Globe** — a 3D view of city-level connections rendered as arcs over the globe |
| 19 | |
| 20 | Use these to spot geographic patterns at a glance — unexpected destinations, asymmetric traffic, CDN routing. |
| 21 | |
| 22 |  |
| 23 | |
| 24 | Country map with top-N pushed to 500, so practically every country with traffic shows up. Edge thickness is bandwidth aggregated per country pair. |
| 25 | |
| 26 | ## How they work |
| 27 | |
| 28 | For each map view, the dashboard: |
| 29 | |
| 30 | 1. Forces a specific aggregation. You don't pick `group_by` for these views — the view picks for you. |
| 31 | 2. Runs the aggregation across your time range and filters. |
| 32 | 3. Renders the top-N (25/50/100/200/500) results as edges on the map. |
| 33 | 4. Same aggregation drives the side-panel list of countries / cities. The list and the map are two views of the same data. |
| 34 | |
| 35 | The forced aggregations are: |
| 36 | |
| 37 | | View | Forced group-by | |
| 38 | |---|---| |
| 39 | | Country map | `SRC_COUNTRY`, `DST_COUNTRY` | |
| 40 | | State map | `SRC_COUNTRY`, `SRC_GEO_STATE`, `DST_COUNTRY`, `DST_GEO_STATE` | |
| 41 | | City map | `SRC_COUNTRY`, `SRC_GEO_STATE`, `SRC_GEO_CITY`, latitude, longitude (source + destination) | |
| 42 | | Globe | Same as city map | |
| 43 | |
| 44 | Edge width is proportional to your sort metric (bytes or packets). The geographic coordinates needed to draw cities and arcs come from the response itself — they're already enriched into each flow record by the time the dashboard renders. You don't need a separate city-coordinates database in the dashboard. |
| 45 | |
| 46 | ## Country and state vs city / globe |
| 47 | |
| 48 | The country map and state map can use the rollup tiers. They're cheap over long time windows. |
| 49 | |
| 50 | The city map and the globe **need raw-tier data**. City, latitude, and longitude are dropped from the rollup tiers (1m / 5m / 1h) to keep cardinality manageable. So: |
| 51 | |
| 52 | - Country / state map over the last 30 days — fine, uses the 1-hour tier. |
| 53 | - City map over the last 30 days — likely empty. Raw-tier retention defaults to its own 10GB / 7d limits; busy collectors often hit the raw-tier size cap before 7 days. |
| 54 | |
| 55 | If your city map looks empty over a long window, try the country map first to confirm data is arriving, then narrow the time range until the city map fills in. |
| 56 | |
| 57 | ## Tooltips |
| 58 | |
| 59 | Hover over a country, state, city, or arc to see a tooltip. The tooltip shows the same fields as the underlying row — endpoints, byte and packet counts. Click does **not** drill down to a different view; the maps are read-only with respect to navigation. To change perspective (e.g., "show me traffic for this country only"), use the filter ribbon to add a `SRC_COUNTRY` or `DST_COUNTRY` selection. |
| 60 | |
| 61 |  |
| 62 | |
| 63 | State map with top-N at 500, zoomed over the US. The tooltip on the link between Attica (Greece) and California shows bidirectional traffic — bytes and packets in each direction. |
| 64 | |
| 65 |  |
| 66 | |
| 67 | City map with top-N at 500, zoomed over Europe. Dozens of European cities appear connected by edges weighted by bandwidth. |
| 68 | |
| 69 |  |
| 70 | |
| 71 | Globe view, top-N at 500, rotated over the Atlantic. The 3D projection shows US cities and EU cities at the curvy edges, with arcs (bandwidth-thickness) bridging them. |
| 72 | |
| 73 | ## Things to know |
| 74 | |
| 75 | ### GeoIP is required |
| 76 | |
| 77 | Without a GeoIP database, country / state / city / coordinate fields are empty and the maps are blank. Native packages include a stock DB-IP database — see the [DB-IP integration card](/src/crates/netflow-plugin/integrations/db-ip_ip_intelligence.md) and the [Enrichment Intel Downloader](/docs/network-flows/intel-downloader.md). Source builds need the operator to run the downloader once. |
| 78 | |
| 79 | ### CDN traffic shifts |
| 80 | |
| 81 | Your traffic to a SaaS provider may resolve to one country today and another tomorrow because the CDN's routing changed. This is normal CDN behaviour, not a security incident. ASN-based aggregation is more stable for cloud / CDN traffic than country-based — see the [Anti-patterns page](/docs/network-flows/anti-patterns.md) "Geographic firewall of shame". |
| 82 | |
| 83 | ### Bidirectional traffic on the map |
| 84 | |
| 85 | Bidirectional traffic between two endpoints produces two separate flow records (one per direction) and renders as two distinct edges (A→B and B→A). The two directions are usually asymmetric in volume — for example, a download is large in one direction and small in the other. To see only one direction, filter on a specific source or destination. |
| 86 | |
| 87 | ### Globe vs City Map |
| 88 | |
| 89 | The globe and city map render the same data with the same table beneath. The 2D city map is best for precise comparisons within a continent. The 3D globe is best when distance and great-circle paths matter — transcontinental traffic, undersea cable corridors, intercontinental CDN routing. Pick the one that fits the question. |
| 90 | |
| 91 | ## What controls are available |
| 92 | |
| 93 | - **Time range** — Netdata's global time picker |
| 94 | - **Filters** — facet selections + autocomplete + full-text search |
| 95 | - **Top-N** — 25 / 50 / 100 / 200 / 500 |
| 96 | - **Sort by** — bytes or packets (determines edge weight and the side-list ranking) |
| 97 | - **Group-by** — locked to the view-specific aggregation; not user-configurable for maps |
| 98 | |
| 99 | ## Things that go wrong |
| 100 | |
| 101 | - **City map empty.** Time range exceeds raw-tier retention. Narrow the range, or use country/state map for a wider view. |
| 102 | - **Ireland or Singapore showing up unexpectedly.** Probably AWS/GCP/Azure shifting CDN routing. ASN-based aggregation is more stable. |
| 103 | - **A whole country disappears.** Your filter excluded it. Check the filter ribbon. |
| 104 | - **No data on globe but city map works.** Both should fail or succeed identically — they consume the same response. If they diverge, that's a dashboard bug worth reporting. |
| 105 | |
| 106 | ## What's next |
| 107 | |
| 108 | - [Enrichment](/docs/network-flows/enrichment.md) — Order of evaluation and the MMDB shared mechanism that drives geographic visualisation. |
| 109 | - [DB-IP integration card](/src/crates/netflow-plugin/integrations/db-ip_ip_intelligence.md) — The default GeoIP source that ships with Netdata. |
| 110 | - [Static Metadata integration card](/src/crates/netflow-plugin/integrations/static_metadata.md) — Declare your internal networks to override GeoIP for RFC 1918. |
| 111 | - [Filters and Facets](/docs/network-flows/visualization/filters-facets.md) — Narrowing geographic views. |
| 112 | - [Anti-patterns](/docs/network-flows/anti-patterns.md) — Why "alert on traffic to country X" is fragile. |