> ## 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**.

<Tip>
  **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)
</Tip>

## Monitor types

DevHelm supports six monitor types:

<CardGroup cols={3}>
  <Card title="HTTP" icon="globe" href="/monitoring/http/overview">
    Web endpoints, APIs, health checks. Supports headers, auth, TLS verification, and 11 assertion types.
  </Card>

  <Card title="TCP" icon="plug" href="/monitoring/tcp/overview">
    Port connectivity checks. Verify services accept connections with response time thresholds.
  </Card>

  <Card title="DNS" icon="server" href="/monitoring/dns/overview">
    Domain resolution. Verify records resolve correctly with expected values, TTLs, and response times.
  </Card>

  <Card title="ICMP" icon="wifi" href="/monitoring/icmp/overview">
    Host reachability via ping. Measure response time and packet loss.
  </Card>

  <Card title="MCP Server" icon="robot" href="/monitoring/mcp-server/overview">
    AI tool server availability. Verify MCP servers start, respond, and list expected tools.
  </Card>

  <Card title="Heartbeat" icon="heart-pulse" href="/monitoring/heartbeat/overview">
    Passive monitoring. Your service pings DevHelm — an incident opens if pings stop arriving.
  </Card>
</CardGroup>

## 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 <token>` |
| `basic` | `Authorization: Basic <base64>` |
| `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 |

<Warning>
  Don't manage the same monitor through both YAML and Terraform. Pick one source of truth per resource.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP monitors" icon="globe" href="/monitoring/http/overview">
    The most feature-rich monitor type — endpoints, APIs, TLS, assertions.
  </Card>

  <Card title="Monitors guide" icon="wrench" href="/guides/monitors">
    Step-by-step guide to creating and configuring monitors.
  </Card>

  <Card title="First HTTP monitor" icon="rocket" href="/guides/first-http-monitor">
    Create your first HTTP monitor end-to-end.
  </Card>

  <Card title="Monitoring as Code" icon="code" href="/mac/yaml/monitors">
    Define monitors in YAML.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.