Grid Checks

Grid checks allow you to monitor multiple dimensions simultaneously in a single check. Instead of creating separate checks for each store, region, API endpoint, or product, you can monitor them all together and see issues at a glance.

When to Use Grid Checks

Use grid checks when you want to:

Monitor the same metric across multiple entities (stores, regions, services, etc.)
Detect when specific entities stop reporting data
Alert when new entities appear unexpectedly
See health status across many dimensions in one view

How Grid Checks Work

Key Insight: Your SQL query defines WHAT data to check. The condition type defines HOW to evaluate it.

Query Format

Grid checks work with two columns:

name - The dimension/entity you’re monitoring (store name, region, endpoint, etc.)
value - The metric you’re checking (count, amount, status, etc.)

-- Example: Monitor order volume by region
SELECT
  region as name,
  COUNT(*) as value
FROM orders
WHERE created_at >= NOW() - INTERVAL '15 minutes'
GROUP BY region

Two-column auto-aliasing: if your query returns exactly two columns, you don’t have to alias them — the first column (by SELECT order) is treated as name and the second as value automatically. If only one of name/value is present, the other column fills the missing one. So this works too:

-- No aliases needed: `region` becomes name, `order_count` becomes value
SELECT region, COUNT(*) AS order_count
FROM orders
WHERE created_at >= NOW() - INTERVAL '15 minutes'
GROUP BY region

Explicit AS name / AS value aliases are still recommended for clarity, and are required when your query returns three or more columns (Alertee can’t guess which column is the dimension and which is the metric). Extra columns beyond name/value are preserved and can be used for labels/display. Each time the check runs, it creates a snapshot of all your dimensions and their values.

Condition Types

Grid checks support four simple condition types:

Polarity: the comparison you set describes the healthy state of each cell — the same as a single-value check — and the check alerts on cells that don’t satisfy it.

1. Every Cell (`all_cells`)

Every row must satisfy the condition; alert if ANY row fails. Use case: Each entity should be healthy — alert on any that isn’t. Example: Alert if any store has fewer than 5 orders

SELECT
  store_name as name,
  COUNT(*) as value
FROM orders
WHERE created_at >= NOW() - INTERVAL '1 hour'
GROUP BY store_name

Condition: all_cells where each cell’s value >= 5 Result: “Alert! Store ‘Downtown’ has 3 orders (not >= 5)“

2. At Least One Cell (`any_cell`)

At least one row must satisfy the condition; alert only if NONE do. Use case: A pool where at least one member must be healthy. Example: Alert if no replica is caught up

SELECT
  replica as name,
  lag_seconds as value
FROM replication_status

Condition: any_cell where each cell’s value <= 5 Result: “Alert! No cell satisfies <= 5 (at least one required)“

3. Dimension Missing

Alert if dimensions from the previous run are absent from current results. Use case: Detect when entities stop reporting data. Example: Alert if regions that were reporting stop sending data

SELECT
  region as name,
  COUNT(*) as value
FROM orders
WHERE created_at >= NOW() - INTERVAL '15 minutes'
GROUP BY region

Condition: dimension_missing (no configuration needed - automatically compares against last run) How it works: On each run, Alertee compares current dimensions against the previous run. If regions like “us-west” or “eu-central” were present before but are missing now, you’ll get alerted. Result: “Alert! Missing dimensions (were present in last run): [us-west, eu-central]“

4. Dimension Added

Alert if new dimensions appear that weren’t in the previous run. Use case: Detect when new entities appear unexpectedly. Example: Alert when a new service appears

SELECT
  service_name as name,
  COUNT(*) as value
FROM service_heartbeats
WHERE timestamp >= NOW() - INTERVAL '10 minutes'
GROUP BY service_name

Condition: dimension_added (no configuration needed - automatically compares against last run) How it works: On each run, Alertee compares current dimensions against the previous run. If new services like “rogue-service” appear that weren’t present before, you’ll get alerted. Result: “Alert! New dimensions detected (not in last run): [rogue-service]“

Advanced: Custom Dimension Columns

By default, grid checks look for a column named name to identify dimensions. You can specify a different column: Condition: dimension_missing with dimension_column: "user_id" and expected dimensions ["user-123", "user-456"] This allows you to check any categorical column in your results.

Best Practices

1. Use SQL for Filtering, Not UI

Instead of using complex UI filters, use SQL WHERE clauses: Good:

SELECT
  store_name as name,
  COUNT(*) as value
FROM orders
WHERE
  created_at >= NOW() - INTERVAL '1 hour'
  AND store_type = 'flagship'  -- Filter in SQL
GROUP BY store_name

Avoid: Filtering “flagship” stores in the UI after the query runs.

2. Keep Queries Simple

Your query runs on every check interval. Keep it performant:

Use indexes on filtered columns
Limit time ranges to recent data
Use GROUP BY to aggregate, not return raw rows

3. Use Time Windows That Match Check Intervals

If your check runs every 15 minutes, query data from the last 15 minutes:

WHERE created_at >= NOW() - INTERVAL '15 minutes'

This ensures you’re always checking fresh, incremental data.

4. Start with “Every Cell” Conditions

Most use cases need all_cells — assert that every entity is healthy and alert on any that isn’t. Reserve any_cell for pools where only one member needs to be healthy (alert when none are).

Note: the worked examples further down this doc still use the older “alert when a cell matches the problem” phrasing and are being revised to the healthy-assertion model described above.

5. One condition per check

A check has a single condition and severity. To watch the same query at two severities (e.g. warning at one threshold, critical at another), or to combine a value check with dimension_missing, create separate checks over the same query — each with its own condition and severity.

Common Patterns

Pattern 1: Service Health Monitoring

Monitor if all services are healthy:

SELECT
  service_name as name,
  CASE
    WHEN last_heartbeat > NOW() - INTERVAL '5 minutes' THEN 1
    ELSE 0
  END as value
FROM services

Condition: all_cells where value = 1 (critical) — every service must be up (1); alerts on any that’s down. Add a second check with dimension_missing to catch a service that stops reporting entirely.

Pattern 2: Regional Metrics

Track metrics across regions:

SELECT
  region as name,
  COUNT(DISTINCT user_id) as value
FROM user_events
WHERE timestamp >= NOW() - INTERVAL '1 hour'
GROUP BY region

Condition: all_cells where value >= 100 (warning) — every region must stay at or above 100 active users; alerts on any that drops below.

Pattern 3: API Endpoint Performance

Monitor p95 latency per endpoint:

SELECT
  endpoint as name,
  PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY duration_ms) as value
FROM api_requests
WHERE timestamp >= NOW() - INTERVAL '10 minutes'
GROUP BY endpoint

Condition: all_cells where value <= 2000 (warning) — every endpoint’s p95 must stay at or below 2000 ms; alerts on any that’s slower. For a stricter critical tier, add a second check with all_cells where value <= 5000.

Pattern 4: Inventory Tracking

Alert on low stock across products:

SELECT
  product_sku as name,
  current_stock as value
FROM inventory
WHERE category = 'high-priority'

Condition: all_cells where value >= 10 (warning) — every product must keep at least 10 in stock; alerts on any that runs low.

Visualization

Grid checks display results in two views:

Current Snapshot: A table showing the latest value for each dimension
Historical Grid: A heatmap showing how values changed over time
- X-axis: Time (from check execution history)
- Y-axis: Dimensions (from name column)
- Cell colors: Green (pass), Yellow (warning), Red (critical)
- Sort (the ↕ icon): order dimensions by name (A–Z) or by Recently updated, which floats the dimensions whose value changed most recently to the top. The choice is remembered per browser.

The historical grid makes it easy to spot patterns:

Which dimensions fail most often?
Are there specific times when issues occur?
Are problems isolated or system-wide?

Limitations

Maximum 100 rows returned per check (for performance)
Query timeout: 30 seconds
Column names name and value are required (or specify custom dimension_column)

Troubleshooting

”Query returned multiple columns”

Your query returns more than name and value. Grid checks only support two columns. Remove extra columns or create a single-value check instead.

”Missing dimensions” alert on first run

dimension_missing and dimension_added conditions require at least one previous successful run to compare against. On the first run, these conditions will not trigger any alerts since there’s no historical data yet. After the first run, each subsequent run will compare dimensions against the previous run to detect changes.

Check runs but no grid appears

Verify your query returns columns named exactly name and value. Column names are case-sensitive in some databases.

Examples

Example 1: E-commerce Store Monitoring

Monitor order volume across all stores, alert if any store drops to zero:

SELECT
  store_code as name,
  COUNT(*) as value
FROM orders
WHERE created_at >= NOW() - INTERVAL '30 minutes'
GROUP BY store_code

Condition: all_cells where value > 0 (critical: “Store has no orders!”) — every store must have orders; alerts on any that drops to zero. Add a second check with dimension_missing to catch a store that stops reporting.

Example 2: Multi-Region API Health

Track API success rate by region:

SELECT
  region as name,
  ROUND(
    100.0 * SUM(CASE WHEN status_code < 500 THEN 1 ELSE 0 END) / COUNT(*),
    2
  ) as value
FROM api_logs
WHERE timestamp >= NOW() - INTERVAL '5 minutes'
GROUP BY region

Condition: all_cells where value >= 95 (critical: “API success rate in dropped to %”) — every region must stay at or above 95%; alerts on any that drops below.

Example 3: Worker Queue Monitoring

Monitor queue lengths across different job types:

SELECT
  job_type as name,
  COUNT(*) as value
FROM job_queue
WHERE status = 'pending'
GROUP BY job_type

Condition: all_cells where value <= 1000 (warning: “Queue backlog for ”) — every queue must stay at or below 1000 pending jobs; alerts on any that backs up. Add a second check with dimension_added to flag a new job type.

Next Steps

Create your first grid check from the Checks page
Test your query using “Test Query” before saving
Start with all_cells (every dimension must be healthy) — it fits most use cases; reserve any_cell for “at least one must be healthy” pools
Use the historical grid to identify patterns and refine your thresholds

Getting started

Checks

Inbox

Alerts

Account

Status

Grid checks

Grid Checks

When to Use Grid Checks

How Grid Checks Work

Query Format

Condition Types

1. Every Cell (`all_cells`)

2. At Least One Cell (`any_cell`)

3. Dimension Missing

4. Dimension Added

Advanced: Custom Dimension Columns

Best Practices

1. Use SQL for Filtering, Not UI

2. Keep Queries Simple

3. Use Time Windows That Match Check Intervals

4. Start with “Every Cell” Conditions

5. One condition per check

Common Patterns

Pattern 1: Service Health Monitoring

Pattern 2: Regional Metrics

Pattern 3: API Endpoint Performance

Pattern 4: Inventory Tracking

Visualization

Limitations

Troubleshooting

”Query returned multiple columns”

”Missing dimensions” alert on first run

Check runs but no grid appears

Examples

Example 1: E-commerce Store Monitoring

Example 2: Multi-Region API Health

Example 3: Worker Queue Monitoring

Next Steps

​Grid Checks

​When to Use Grid Checks

​How Grid Checks Work

​Query Format

​Condition Types

​1. Every Cell (all_cells)

​2. At Least One Cell (any_cell)

​3. Dimension Missing

​4. Dimension Added

​Advanced: Custom Dimension Columns

​Best Practices

​1. Use SQL for Filtering, Not UI

​2. Keep Queries Simple

​3. Use Time Windows That Match Check Intervals

​4. Start with “Every Cell” Conditions

​5. One condition per check

​Common Patterns

​Pattern 1: Service Health Monitoring

​Pattern 2: Regional Metrics

​Pattern 3: API Endpoint Performance

​Pattern 4: Inventory Tracking

​Visualization

​Limitations

​Troubleshooting

​”Query returned multiple columns”

​”Missing dimensions” alert on first run

​Check runs but no grid appears

​Examples

​Example 1: E-commerce Store Monitoring

​Example 2: Multi-Region API Health

​Example 3: Worker Queue Monitoring

​Next Steps

Grid Checks

When to Use Grid Checks

How Grid Checks Work

Query Format

Condition Types

1. Every Cell (`all_cells`)

2. At Least One Cell (`any_cell`)

3. Dimension Missing

4. Dimension Added

Advanced: Custom Dimension Columns

Best Practices

1. Use SQL for Filtering, Not UI

2. Keep Queries Simple

3. Use Time Windows That Match Check Intervals

4. Start with “Every Cell” Conditions

5. One condition per check

Common Patterns

Pattern 1: Service Health Monitoring

Pattern 2: Regional Metrics

Pattern 3: API Endpoint Performance

Pattern 4: Inventory Tracking

Visualization

Limitations

Troubleshooting

”Query returned multiple columns”

”Missing dimensions” alert on first run

Check runs but no grid appears

Examples

Example 1: E-commerce Store Monitoring

Example 2: Multi-Region API Health

Example 3: Worker Queue Monitoring

Next Steps