Agent Local Checks

Reference for the exact check types and fields supported by the open-source uptimy-agent.

Overview

Local checks run from the agent and are defined in YAML underchecks. Duration fields use Go-style durations (for example 15s, 60s, 1h). Source of truth: github.com/uptimy/uptimy-agent.

ℹ️ No Inbound Access Required

Local checks operate entirely from within your network. The agent can run fully standalone. Control plane connectivity is optional and only required for centralized telemetry/visibility features.

Common Settings

Every check entry shares these core fields:

Setting	Type	Description
type	string	Check kind, for example `http`, `tcp`, or`disk`
name	string	Unique check identifier referenced by repair rules
service	string	Logical service grouping label
interval	duration	How often the check runs (for example `30s`)
timeout	duration	Max runtime before timeout failure
tags	string array	Optional tags for filtering and grouping
metadata	object	Optional extra key/value metadata

Check Types Reference

1. HTTP Check

HTTP/HTTPS endpoint check.

Field	Type	Description
url	string	Full URL to check, e.g., `http://localhost:8080/health`
method	string	HTTP method (for example GET, POST)
expected_status	integer	Expected HTTP status code. Default: 200.
headers	object	Optional custom headers to include in the request.

HTTP Check Example

{
  "type": "http",
  "name": "api-health",
  "service": "api",
  "url": "http://localhost:3000/api/health",
  "method": "GET",
  "expected_status": 200,
  "interval": "30s",
  "timeout": "5s",
  "tags": ["api", "internal"]
}

2. TCP Check

TCP connectivity check to a host and port.

Field	Type	Description
address	string	Target host:port, for example `localhost:5432`

TCP Check Example

{
  "type": "tcp",
  "name": "postgres",
  "service": "postgres",
  "address": "localhost:5432",
  "interval": "15s",
  "timeout": "5s"
}

3. Process Check

Verify that a specific process is running on the host. The agent scans the process list and matches by process name. If the process is not found, the check fails.

Field	Type	Description
service_name	string	Name of the process to look for, e.g., `nginx` or `postgres`

Process Check Example

{
  "type": "process",
  "name": "nginx-running",
  "service": "nginx",
  "service_name": "nginx",
  "interval": "10s",
  "timeout": "5s"
}

4. Docker Container Check

Monitor the status of a Docker container by name. The check verifies that the container is running and, if a health check is configured on the container, that it reports a healthy state.

Field	Type	Description
container_name	string	Name of the Docker container to monitor, e.g., `redis-cache`

Docker Container Check Example

{
  "type": "docker_container",
  "name": "redis-container",
  "service": "redis",
  "container_name": "redis-cache",
  "interval": "30s",
  "timeout": "10s"
}

5. Docker Swarm Check

Docker Swarm health check. No additional type-specific fields are required beyond the common fields.

Docker Swarm Check Example

{
  "type": "docker_swarm",
  "name": "swarm-health",
  "service": "swarm",
  "interval": "30s",
  "timeout": "10s"
}

6. Disk Check

Monitor disk usage on a specified file system path. The check fails when the usage percentage exceeds your configured threshold, helping you prevent disk-full outages before they happen.

Field	Type	Description
path	string	File system path to monitor, e.g., `/` or `/var/log`
threshold	integer	Usage percentage that triggers a failure. Default: 90.

Disk Usage Check Example

{
  "type": "disk",
  "name": "disk-check",
  "service": "system",
  "path": "/",
  "threshold": 85,
  "interval": "120s",
  "timeout": "10s"
}

7. Memory Check

Monitor system memory utilization. When total memory usage exceeds the configured threshold, the check fails. This helps you detect memory leaks and resource exhaustion early.

Field	Type	Description
threshold	integer	Memory usage percentage that triggers a failure. Default: 90.

Memory Check Example

{
  "type": "memory",
  "name": "memory-check",
  "service": "system",
  "threshold": 90,
  "interval": "60s",
  "timeout": "10s"
}

8. CPU Check

Monitor CPU utilization across all cores. The check samples CPU usage over the timeout window and fails if the average exceeds the configured threshold. Useful for detecting runaway processes and unexpected load spikes.

Field	Type	Description
threshold	integer	CPU usage percentage that triggers a failure. Default: 90.

CPU Check Example

{
  "type": "cpu",
  "name": "cpu-check",
  "service": "system",
  "threshold": 85,
  "interval": "60s",
  "timeout": "10s"
}

9. Certificate Check

TLS certificate expiry check. The agent supports endpoint-based checks with cert_url and file-based checks withcert_path.

Field	Type	Description
cert_url	string	Endpoint form, for example `api.example.com:443`
cert_path	string	Optional path-based certificate source
days_before_expiry	integer	Warning threshold in days

Certificate Check Example

{
  "type": "certificate",
  "name": "api-cert",
  "service": "api",
  "cert_url": "api.example.com:443",
  "days_before_expiry": 30,
  "interval": "3600s",
  "timeout": "30s"
}

💡 Field Names Matter

Use the exact field names from the open-source examples:threshold (not threshold_percent),service_name for process checks, and duration strings like 30s for interval/timeout.

Summary Table

Check Type	Key Config Fields	Typical Interval
HTTP	url, method, expected_status, headers	30s
TCP	address	15s to 30s
Process	service_name	15s
Docker Container	container_name	30s
Docker Swarm	(no extra type-specific fields)	30s
Disk	path, threshold	60s
Memory	threshold	30s
CPU	threshold	30s
Certificate	cert_url or cert_path, days_before_expiry	3600s

⚠️ Agent Permissions

Some checks require elevated permissions. Docker Container checks need access to the Docker socket. Process checks may need root access to see all running processes. Certificate checks using cert_path need read access to that file. Make sure your agent runs with the appropriate permissions.