docs/npm/network-flows/visualization/maps-globe.md
Four geographic views, all driven by the same aggregation engine as the Sankey and Time-Series:
Use these to spot geographic patterns at a glance — unexpected destinations, asymmetric traffic, CDN routing.
Country map with top-N pushed to 500, so practically every country with traffic shows up. Edge thickness is bandwidth aggregated per country pair.
For each map view, the dashboard:
group_by for these views — the view picks for you.The forced aggregations are:
| View | Forced group-by |
|---|---|
| Country map | SRC_COUNTRY, DST_COUNTRY |
| State map | SRC_COUNTRY, SRC_GEO_STATE, DST_COUNTRY, DST_GEO_STATE |
| City map | SRC_COUNTRY, SRC_GEO_STATE, SRC_GEO_CITY, latitude, longitude (source + destination) |
| Globe | Same as city map |
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.
The country map and state map can use the rollup tiers. They're cheap over long time windows.
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:
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.
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.
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.
City map with top-N at 500, zoomed over Europe. Dozens of European cities appear connected by edges weighted by bandwidth.
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.
Without a GeoIP database, country / state / city / coordinate fields are empty and the maps are blank. Native packages and static builds that include the NetFlow plugin (x86_64, ARMv7, and AArch64) include a stock DB-IP database — see the DB-IP integration card and the Enrichment Intel Downloader. Source builds need the operator to run the downloader once.
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 "Geographic firewall of shame".
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.
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.