> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoring Overview
> How DevHelm monitors work — six monitor types, check flow, assertions, probe regions, and incident policies
Monitors are the core building block of DevHelm. A monitor defines **what to check**, **how often**, **from where**, and **what counts as failure**.
**Define monitors in code.** Manage monitors as part of your monitoring-as-code workflow:
[YAML format](/mac/yaml/monitors) · [Terraform](/mac/terraform/monitors) · [CI/CD patterns](/mac/ci-cd/overview)
## Monitor types
DevHelm supports six monitor types:
Web endpoints, APIs, health checks. Supports headers, auth, TLS verification, and 11 assertion types.
Port connectivity checks. Verify services accept connections with response time thresholds.
Domain resolution. Verify records resolve correctly with expected values, TTLs, and response times.
Host reachability via ping. Measure response time and packet loss.
AI tool server availability. Verify MCP servers start, respond, and list expected tools.
Passive monitoring. Your service pings DevHelm — an incident opens if pings stop arriving.
## Check flow
For **active monitors** (HTTP, TCP, DNS, ICMP, MCP Server):
1. DevHelm runs checks from each configured **probe region** at the set **frequency**
2. Each check evaluates all **assertions** and records a result (pass/fail)
3. Results flow into the **incident policy** engine
4. If the policy's trigger rules are met, an incident is created and alerts fire
5. When the monitor recovers, the incident auto-resolves per the recovery policy
For **heartbeat monitors**, the flow is reversed — your service sends periodic pings to a DevHelm endpoint. If a ping doesn't arrive within the expected interval plus grace period, the monitor is marked as down.
## Frequency
Check frequency is configurable from **10 seconds to 86,400 seconds** (24 hours). The minimum frequency depends on your plan. When you omit the frequency, it defaults to **60 seconds** or your plan's minimum, whichever is higher.
| Plan | Minimum frequency |
| ---------- | ----------------- |
| Free | 300s (5 min) |
| Starter | 60s (1 min) |
| Pro | 30s |
| Team | 30s |
| Business | 30s |
| Enterprise | 10s |
## Regions
Monitors run from one or more [probe regions](/monitoring/regions). Multi-region checks enable the incident policy to require failures from multiple locations before opening an incident, reducing false positives.
```bash theme={null}
devhelm monitors create \
--name "API Health" \
--type HTTP \
--url https://api.example.com/health \
--frequency 60 \
--regions us-east,eu-west
```
## Assertions
Assertions define what "healthy" means for your monitor. Each assertion has a **severity** (`fail` or `warn`) and type-specific configuration.
* **fail** severity — contributes to incident creation when the assertion fails
* **warn** severity — records a `DEGRADED` severity hint but doesn't directly trigger `DOWN` incidents
Every monitor type has its own assertion set. HTTP monitors have the most options (11 types), while simpler protocols like TCP have 3.
| Monitor type | Available assertions |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [HTTP](/monitoring/http/assertions) | `status_code`, `response_time`, `body_contains`, `json_path`, `header_value`, `regex_body`, `ssl_expiry`, `response_size`, `redirect_count`, `redirect_target`, `response_time_warn` |
| [TCP](/monitoring/tcp/configuration) | `tcp_connects`, `tcp_response_time`, `tcp_response_time_warn` |
| [DNS](/monitoring/dns/configuration) | `dns_resolves`, `dns_response_time`, `dns_expected_ips`, `dns_expected_cname`, `dns_record_contains`, `dns_record_equals`, `dns_txt_contains`, `dns_min_answers`, `dns_max_answers`, `dns_response_time_warn`, `dns_ttl_low`, `dns_ttl_high` |
| [ICMP](/monitoring/icmp/configuration) | `icmp_reachable`, `icmp_response_time`, `icmp_response_time_warn`, `icmp_packet_loss` |
| [MCP Server](/monitoring/mcp-server/configuration) | `mcp_connects`, `mcp_response_time`, `mcp_has_capability`, `mcp_tool_available`, `mcp_min_tools`, `mcp_protocol_version`, `mcp_response_time_warn`, `mcp_tool_count_changed` |
| [Heartbeat](/monitoring/heartbeat/configuration) | `heartbeat_received`, `heartbeat_max_interval`, `heartbeat_interval_drift`, `heartbeat_payload_contains` |
### Assertion operators
Where an assertion uses an `operator` field, the options are:
| Operator | Behavior |
| -------------- | -------------------- |
| `equals` | Exact match |
| `contains` | Substring match |
| `less_than` | Numeric less-than |
| `greater_than` | Numeric greater-than |
| `matches` | Regex match |
| `range` | Numeric range |
## Authentication
HTTP monitors support authenticated requests via **vault secrets**. Store credentials in the encrypted vault, then reference them in your monitor configuration — by `vaultSecretId` in the API, or by secret name in YAML.
| Auth type | What it sends |
| --------- | ------------------------------- |
| `bearer` | `Authorization: Bearer ` |
| `basic` | `Authorization: Basic ` |
| `header` | Custom header with secret value |
| `api_key` | Named header with API key value |
See [Secrets](/platform/secrets) for vault management and [HTTP configuration](/monitoring/http/configuration) for auth setup.
## Incident policy
Every monitor has an incident policy that controls when incidents open and close. The policy has three components:
* **Trigger rules** — conditions that open an incident (consecutive failures, failures in window, response time)
* **Confirmation** — multi-region confirmation to prevent false positives
* **Recovery** — how many passing checks are required before auto-resolving
See [Incident policies](/incidents/policies) for full details.
## Management modes
Monitors track who manages them via the optional `managedBy` field. It's never
required on create — when omitted, the API defaults it to `API`. Each surface
sets it automatically so drift detection can attribute the change correctly:
| Mode | Set by | Meaning |
| ----------- | ------------------------------ | ----------------------------------- |
| `API` | Direct REST calls | Default when no surface is detected |
| `DASHBOARD` | App at `app.devhelm.io` | Managed through the dashboard UI |
| `CLI` | `devhelm deploy` | Managed by YAML config-as-code |
| `TERRAFORM` | Terraform provider | Managed by Terraform state |
| `MCP` | DevHelm MCP server (AI agents) | Managed via an MCP-connected client |
Don't manage the same monitor through both YAML and Terraform. Pick one source of truth per resource.
## Next steps
The most feature-rich monitor type — endpoints, APIs, TLS, assertions.
Step-by-step guide to creating and configuring monitors.
Create your first HTTP monitor end-to-end.
Define monitors in YAML.