Stat panels can display a single, important metric, but they become truly powerful when you add thresholds to color-code the values based on their severity.
Let’s say you’re monitoring the number of active users on your web application. You want to know at a glance if things are normal, getting a bit busy, or if you’re about to hit a critical limit.
Here’s a basic Stat panel configuration in Grafana showing the current active user count:
{
"datasource": "prometheus",
"gridPos": {
"h": 4,
"w": 4,
"x": 0,
"y": 0
},
"id": 1,
"options": {
"colorMode": "value",
"graphMode": "none",
"justifyMode": "auto",
"orientation": "auto",
"reduceOptions": {
"calcs": [
"lastNotNull"
],
"fields": [],
"values": false
},
"textMode": "auto",
"wideLayout": false
},
"pluginVersion": "9.5.1",
"targets": [
{
"datasource": {
"type": "prometheus",
"uid": "prometheus"
},
"editorMode": "builder",
"expr": "up{job=\"your_app_service\"}",
"legendFormat": "__auto",
"queryType": "range",
"refId": "A"
}
],
"title": "Active Users",
"type": "stat"
}
Now, let’s add thresholds. We’ll define three states:
- Green: Below 1000 users (normal)
- Orange: Between 1000 and 2000 users (approaching capacity)
- Red: Above 2000 users (critical)
In the Grafana UI, you’d navigate to your Stat panel’s configuration. Under the "Panel options" or "Display" tab (depending on your Grafana version), you’ll find a "Thresholds" section.
You can set these thresholds directly. For our active users example, you’d enter:
- Base: 0 (This is the default, representing the lowest possible value).
- Threshold 1: 1000
- Threshold 2: 2000
Then, you’d assign colors to these thresholds. Grafana typically uses a color picker.
- For values < 1000, you’d select green.
- For values between 1000 and 2000, you’d select orange.
- For values > 2000, you’d select red.
The colorMode option in the JSON config is crucial here. Setting it to "value" means the entire stat panel’s value will change color based on the thresholds. Other options like "background" color the panel’s background, and "card" colors the entire card surrounding the stat. For immediate visual feedback on the metric itself, "value" is usually best.
The reduceOptions section dictates how the data from your query is aggregated into a single number for the stat panel. lastNotNull is common for time-series data, ensuring you always see the most recent valid data point.
When the active user count is 850, the panel will display "850" in green. If it jumps to 1500, it will show "1500" in orange. If it surges to 2200, you’ll see "2200" in red.
The actual data displayed for the stat panel is determined by the expr in your query. If your Prometheus query up{job="your_app_service"} returns a single value (e.g., 1 for up, 0 for down), you might need to adjust your query to get the count of active users. A more typical query for active users might look like sum(active_users_count{job="your_app_service"}).
The "Graph mode" setting also affects appearance. "none" means no graph is shown within the stat panel. "area" or "line" would overlay a mini-graph of the metric’s recent history. For pure threshold indication, "none" is often preferred.
The justifyMode setting controls text alignment. "auto" is usually fine, but you can explicitly set it to "center", "auto", or "flex-start" to fine-tune the layout.
The real power comes from understanding that these thresholds are not just visual; they are direct indicators of system state. A red stat panel is a clear signal that an operator needs to investigate immediately, while an orange one prompts proactive monitoring.
A common pitfall is setting thresholds that are too sensitive or too broad, leading to alert fatigue or missed critical events. It’s essential to align these thresholds with your application’s performance SLOs and understand the operational impact of each state. Grafana’s thresholding allows for a single query to drive multiple visual states, simplifying dashboard design and improving readability.
The next step is often to integrate these visual cues with alerting, so that a red stat panel automatically triggers a PagerDuty incident.