Service Check
A Service Check is the mechanism by which a Datadog Agent check reports the health of a monitored target as one of four statuses: OK, WARNING, CRITICAL, or UNKNOWN. It is a separate lineage from metrics, which track how a value changes; a service check tells you whether a service is responding.
Overview
A service check is a type of data that Datadog Agent integrations and custom checks use to report the status of a monitored target. Instead of a number, it sends one of four statuses, OK (0), WARNING (1), CRITICAL (2), or UNKNOWN (3), on every run, and it is used on the Check Summary page, in the Check status dashboard widget, and in service check monitors. It cannot be drawn as a time series graph the way a metric can, but it suits decisions such as alerting after a specified number of consecutive CRITICAL results or when a given percentage of a cluster is down. You care about it when you see a screen with nothing but OK / CRITICAL results and no metrics or logs, and when you decide how availability monitoring should alert.
Data that carries a status rather than a value
A Service Check is a type of data by which a Datadog Agent check reports the health of a monitored target. The official documentation explains that service checks characterize the status of a service so it can be monitored in Datadog. Per the official description, they watch whether a service is up or down, and an alert fires when the Agent fails to connect to that service a specified number of times in a row (as of September 2026, Source: Service Check). Where a metric carries a value such as "CPU usage 73%", a service check carries "could this DB be reached?" as one of four statuses. One status is sent per check run, and the statuses do not accumulate as time series values. This difference leads to the property described below: a service check cannot be graphed, but it can be turned into a monitor.
The four statuses and their numeric codes
From a custom Agent check you submit with self.service_check(name, status, tags, hostname, message), where status is an integer from 0 to 3. You can attach the reason for the status in message (as of September 2026, Source: Service Check Submission: Agent Check).
| Status | status value | Treatment in a service check monitor |
|---|---|---|
| OK | 0 | N consecutive OK results recover the alert |
| WARNING | 1 | Counts toward the warning threshold of a cluster alert |
| CRITICAL | 2 | N consecutive CRITICAL results trigger the alert |
| UNKNOWN | 3 | You choose whether to notify. When notifying, the status bar turns the same gray as No Data while the overall monitor stays OK |
Besides custom Agent checks, you can submit through DogStatsD and the API; the submission methods themselves are left to the DogStatsD entry. Many integrations ship their own service checks, so you write your own only when an integration lacks one or when you want to watch the availability of an in-house service.
Cannot be graphed, but can be a monitor
Service checks appear in three places. The Check Summary page lists every check reported from your entire infrastructure over the past day, and selecting one shows its status and tags. On dashboards you can place a Check status widget, specifying the aggregation period and whether the scope is a single check or a cluster grouped by tags. The third place is the service check monitor. The official documentation states explicitly that service checks cannot be graphed over time like metrics, but they can be made into monitors (as of September 2026, Source: Service Check). Service checks are not suited to the request "I want to see the status history as a line chart"; the design there is to collect a metric such as response time alongside them. Most Integrations emit both metrics and service checks, so you read the trend of the value together with whether the service is up.
Alerting after N in a row - check alerts and cluster alerts
A monitor has two kinds of conditions. A check alert tracks consecutive statuses per group of the check and compares them to thresholds.
- Raise a separate alert for each group reporting the check (in a service check monitor you specify the groups yourself)
- Alert after N consecutive CRITICAL results (set to 1 to fire on the first failure)
- Choose whether or not to notify on UNKNOWN
- Recover after N consecutive OK results (for example, treat 4 as fixed)
A cluster alert counts each combination of tags as one check, uses only its latest status, and compares the percentage of checks in a given status to a threshold (as of September 2026, Source: Service Check Monitor). The official example groups by environment and alerts when more than 70% of the checks in any environment are CRITICAL, or warns when more than 70% are WARN. In a setup where multiple services share a host and some failures are tolerated, the official recommendation is that a cluster alert catches service degradation sooner than watching whether the host is alive.
Do not confuse UNKNOWN with No Data
The relationship between UNKNOWN and No Data is easy to misread. UNKNOWN is a status where the check ran and reported "cannot determine", and in a monitor you choose whether to notify on it. If you choose to notify, a notification is sent on the transition to UNKNOWN and the status bar uses the same gray as No Data, but the overall status of the monitor stays OK (as of September 2026, Source: Service Check Monitor). No Data, by contrast, is the state a monitor takes when the check result itself never arrived, representing the silence of a stopped Agent or a vanished host. The gray is the same, but "reported as undeterminable" and "no report arrived" call for different ways of hunting the cause. You think about service checks when choosing a monitor type for situations where you only want to know "is it up?", and when you want to understand what the OK / CRITICAL results lined up on an integration's screen mean. Remember first that it means a status rather than a number, and you will not get lost.