Grafana’s Geomap panel can overlay your time-series data onto a geographical map, but it’s not just for showing where things are; it’s about understanding the dynamics of your distributed systems through their physical locations.
Let’s see it in action. Imagine you have a fleet of IoT devices reporting their GPS coordinates and some metric, say, battery voltage.
[
{
"time": 1678886400000,
"location": [-74.0060, 40.7128],
"battery_voltage": 3.8
},
{
"time": 1678886400000,
"location": [-118.2437, 34.0522],
"battery_voltage": 3.5
},
{
"time": 1678886460000,
"location": [-74.0060, 40.7128],
"battery_voltage": 3.7
},
{
"time": 1678886460000,
"location": [-118.2437, 34.0522],
"battery_voltage": 3.4
},
{
"time": 1678886520000,
"location": [-74.0060, 40.7128],
"battery_voltage": 3.7
},
{
"time": 1678886520000,
"location": [-118.2437, 34.0522],
"battery_voltage": 3.3
}
]
This JSON represents data points for two devices, one near New York City and one near Los Angeles, with their battery voltage decreasing over time.
In Grafana, you’d set up a query that returns data with at least two fields: one for location (typically as [longitude, latitude] or latitude, longitude) and one or more fields for the metrics you want to visualize (like battery_voltage).
The Geomap panel then takes this data and renders it on a map. You can configure:
- Map Provider: OpenStreetMap, Mapbox, or other tile servers.
- Location Data: How your data is structured (e.g., GeoJSON, CSV, or your specific time-series format).
- Markers: How each data point is represented (e.g., circles, squares).
- Coloring: Mapping metric values to colors. For example, low battery voltage could be red, high could be green. This is where the dynamics come in. You can immediately spot devices in distress.
- Tooltips: Displaying detailed information when hovering over a marker.
- Heatmaps: Aggregating points to show density.
- Circles: Sizing markers based on a metric.
The core problem Geomap solves is the cognitive load of correlating disparate time-series data with physical locations. Instead of scanning tables or line graphs for devices in specific regions, you see a map where the color and size of markers instantly tell you the state of your distributed assets. It’s about making the where as important as the when and what.
When you’re setting up your Geomap panel, you’ll notice options for "Location mode" and "Format as." For time-series data like the example above, you’ll likely choose "Location mode: Coordinates" and "Format as: Table." Within the "Table" format, you’ll then map your data columns to the Geomap panel’s expectations: one column for latitude, one for longitude, and then your metric columns. The panel is smart enough to infer the [lon, lat] structure if your field names are descriptive, but explicit mapping is always best. You can even use Grafana’s built-in geo_hash or geohash functions in your queries to generate location strings if your raw data doesn’t include coordinates directly, allowing you to visualize based on coarser geographical regions.
The most powerful visualization isn’t just static points, but how they change over time. By setting your Geomap panel’s time range and refresh interval appropriately, you can watch your data points move and change color across the map, effectively turning your dashboard into a real-time operational view of your geographically distributed infrastructure. This allows for proactive identification of issues that might be localized to a specific region or even a single device before they escalate.
Understanding how to transform your raw location data (latitude/longitude pairs) into the GeoJSON format that Grafana’s Geomap panel often prefers for more complex geometries, like polygons or lines, is the next step in advanced spatial analysis.