# Uptime Kuma Monitor Types: Complete Implementation Guide and Architecture

> Explore Uptime Kuma monitor types and their implementation. Discover how Uptime Kuma supports over 30 monitors including HTTP, databases, and Playwright for robust system monitoring.

- Repository: [Louis Lam/uptime-kuma](https://github.com/louislam/uptime-kuma)
- Tags: deep-dive
- Published: 2026-02-28

---

**Uptime Kuma supports over 30 distinct monitor types—including HTTP/HTTPS, TCP ports, databases (MySQL, PostgreSQL, MongoDB, Redis), message queues (RabbitMQ, MQTT), network protocols (DNS, SNMP, gRPC), real browser automation (Playwright), and game server queries (Gamedig)—each implemented as a specialized class extending the abstract `MonitorType` base class in `server/monitor-types/`.**

Uptime Kuma is an open-source, self-hosted monitoring tool that tracks service availability through a flexible, plugin-like architecture. Understanding the different Uptime Kuma monitor types and their underlying implementations enables operators to configure precise health checks for everything from simple TCP ports to complex database clusters and real browser interactions.

## How Uptime Kuma Monitor Types Work: The Architecture

The monitoring engine in Uptime Kuma is built around a class-based hierarchy that enforces a consistent contract for all health checks.

### The MonitorType Base Class

All monitor types extend the abstract `MonitorType` class defined in [`server/monitor-types/monitor-type.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/monitor-type.js). This base class establishes the contract that every concrete implementation must follow, ensuring consistent heartbeat handling across the application.

### The Check Method Contract

Every monitor type must implement an async `check(monitor, heartbeat, server)` method. This method receives the monitor configuration object, a heartbeat record to populate, and the server instance. The implementation must update `heartbeat.status` (UP or DOWN), `heartbeat.msg` (human-readable status), and `heartbeat.ping` (latency in milliseconds). Failures are signaled by throwing an Error.

### Scheduler Integration

The [`server/monitor-scheduler.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-scheduler.js) orchestrates the execution loop. It dynamically loads the appropriate monitor class based on the `monitor.type` string stored in the database:

```javascript
const MonitorClass = require(`./monitor-types/${monitor.type}.js`);
const monitorInstance = new MonitorClass();
await monitorInstance.check(monitor, heartbeat, server);

```

## Complete List of Uptime Kuma Monitor Types

Uptime Kuma organizes its 30+ monitor types into logical categories based on the protocols and services they target.

### Network and TCP/IP Monitors

- **port** (`TCPMonitorType`): Performs TCP connection checks using the `tcp-ping` library. Supports TLS certificate validation via `tls.connect` and the helper `checkCertificate`. Located in [`server/monitor-types/tcp.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/tcp.js).

- **ping** (`GlobalpingMonitorType` subtype): Sends ICMP echo requests through the Globalping API. Handles IPv4/IPv6 and TCP-ping modes. Implemented in [`server/monitor-types/globalping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/globalping.js).

- **dns** (Native): Uses `node:dns/promises` for local DNS resolution. Supports A, AAAA, CNAME, MX, TXT records and conditional evaluation of results. Found in [`server/monitor-types/dns.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/dns.js).

- **dns** (Globalping): Performs remote DNS queries from distributed Globalping probes. Supports any DNS record type with keyword matching. Also in [`server/monitor-types/globalping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/globalping.js).

### Web and Application Layer Monitors

- **http / https** (`GlobalpingMonitorType`): Executes HTTP/HTTPS requests via the Globalping infrastructure. Supports custom headers, basic/OAuth2 authentication, TLS handling, and keyword/JSON query validation. Located in [`server/monitor-types/globalping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/globalping.js).

- **websocket-upgrade** (`WebSocketMonitorType`): Validates WebSocket handshake compatibility using the `ws` library. Checks sub-protocols and close codes against user-defined accepted status codes. Found in [`server/monitor-types/websocket-upgrade.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/websocket-upgrade.js).

- **real-browser** (`RealBrowserMonitorType`): Launches a headless Chromium browser via **Playwright**. Navigates to URLs, executes user-defined JavaScript, and validates selectors or keywords. Located in [`server/monitor-types/real-browser-monitor-type.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/real-browser-monitor-type.js).

- **grpc** (`GrpcMonitorType`): Performs gRPC health checks using `@grpc/grpc-js`. Invokes unary methods and validates responses. Found in [`server/monitor-types/grpc.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/grpc.js).

### Database and Message Queue Monitors

- **mysql / mariadb** (`MysqlMonitorType`): Connects using `mysql2` driver. Executes queries and returns row counts or single values for condition evaluation. Located in [`server/monitor-types/mysql.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/mysql.js).

- **postgres** (`PostgresMonitorType`): Uses `pg` (node-postgres) driver. Supports custom SQL queries with conditional expression evaluation. Found in [`server/monitor-types/postgres.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/postgres.js).

- **mssql** (`MssqlMonitorType`): Implements Microsoft SQL Server monitoring using the `mssql` driver. Located in [`server/monitor-types/mssql.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/mssql.js).

- **mongodb** (`MongodbMonitorType`): Uses the native `mongodb` driver to execute `db.command({ ping: 1 })` for health verification. Found in [`server/monitor-types/mongodb.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/mongodb.js).

- **redis** (`RedisMonitorType`): Connects via `ioredis` and sends `PING` commands. Supports authentication. Located in [`server/monitor-types/redis.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/redis.js).

- **rabbitmq** (`RabbitmqMonitorType`): Connects to AMQP endpoints using `amqplib`. Opens channels and optionally creates temporary queues to verify broker health. Found in [`server/monitor-types/rabbitmq.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/rabbitmq.js).

### Infrastructure and Network Protocol Monitors

- **snmp** (`SnmpMonitorType`): Queries SNMP agents using `net-snmp` library. Supports SNMPv1-v3 authentication and OID value evaluation. Located in [`server/monitor-types/snmp.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/snmp.js).

- **mqtt** (`MqttMonitorType`): Connects to MQTT brokers using the `mqtt` library. Supports TLS encryption and validates connection lifecycle events. Found in [`server/monitor-types/mqtt.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/mqtt.js).

- **smtp** (`SmtpMonitorType`): Validates SMTP server availability using `nodemailer`. Supports `STARTTLS` and certificate validation. Optionally sends test emails. Located in [`server/monitor-types/smtp.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/smtp.js).

- **sip-options** (`SipOptionsMonitorType`): Sends SIP OPTIONS requests using [`sip.js`](https://github.com/louislam/uptime-kuma/blob/main/sip.js). Validates response codes and body patterns. Found in [`server/monitor-types/sip-options.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/sip-options.js).

- **tailscale-ping** (`TailscalePing`): Executes the external `tailscale ping` binary via `promisify-child-process` and parses latency from output. Located in [`server/monitor-types/tailscale-ping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/tailscale-ping.js).

- **system-service** (`SystemServiceMonitorType`): Checks systemd services on Linux via `systemctl is-active` and Windows services via PowerShell `Get-Service`. Implements command injection sanitization. Located in [`server/monitor-types/system-service.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/system-service.js).

### Specialized and Aggregate Monitors

- **gamedig** (`GameDigMonitorType`): Queries game servers (Minecraft, CS:GO, etc.) using the `gamedig` library. Returns player counts and latency. Located in [`server/monitor-types/gamedig.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/gamedig.js).

- **manual** (`ManualMonitorType`): No automated network calls. Status is set to UP only when a user manually clicks "Resume" in the UI. Located in [`server/monitor-types/manual.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/manual.js).

- **group** (`GroupMonitorType`): Aggregates status from child monitors. The `check` method reports status based on member states rather than performing independent network operations. Located in [`server/monitor-types/group.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/group.js).

## Practical Implementation Examples

### Adding a TCP Port Monitor via API

To create a TCP port monitor that checks TLS certificate validity:

```bash
curl -X POST "https://my-kuma.example/api/monitor" \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type":"port",
        "name":"My-Web-Port",
        "hostname":"example.com",
        "port":443,
        "interval":60,
        "expected_tls_alert":"none"
      }'

```

The server stores `"type":"port"` and instantiates `TCPMonitorType` from [`server/monitor-types/tcp.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/tcp.js).

### Configuring an HTTP Monitor with Globalping

For distributed HTTP monitoring using the Globalping network:

```bash
curl -X POST "https://my-kuma.example/api/monitor" \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type":"http",
        "subtype":"http",
        "name":"My-Site",
        "url":"https://example.com",
        "method":"GET",
        "interval":30,
        "accepted_statuscodes_json":"[200,301,302]"
      }'

```

This triggers `GlobalpingMonitorType.http()` in [`server/monitor-types/globalping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/globalping.js) to build the measurement and validate response codes.

### Setting Up Native DNS Resolution

To monitor DNS records using the local resolver:

```bash
curl -X POST "https://my-kuma.example/api/monitor" \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "type":"dns",
        "name":"My-Domain-A",
        "hostname":"example.com",
        "dns_resolve_type":"A",
        "interval":120
      }'

```

This invokes `DnsMonitorType.check()` in [`server/monitor-types/dns.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/dns.js), which calls `dnsResolve()` using Node.js native DNS promises.

## Summary

- Uptime Kuma implements **over 30 monitor types** through an extensible class hierarchy in `server/monitor-types/`.
- All monitors extend the abstract **`MonitorType`** class and implement an async **`check(monitor, heartbeat, server)`** method that updates heartbeat status, message, and latency.
- The **scheduler** dynamically loads monitor classes based on the `monitor.type` database field, enabling modular addition of new protocols without core code changes.
- Monitor categories include **network** (TCP, DNS, ICMP), **web** (HTTP, WebSocket, Browser), **databases** (SQL, NoSQL, caches), **infrastructure** (SNMP, MQTT, systemd), and **specialized** (GameDig, gRPC, Manual).

## Frequently Asked Questions

### How does Uptime Kuma determine which monitor type class to instantiate?

The scheduler reads the `type` field from the monitor database record and dynamically requires the corresponding module using `require(\`./monitor-types/${monitor.type}.js\`)`. This pattern allows the system to load the correct implementation class—such as `TCPMonitorType` for `"port"` or `DnsMonitorType` for `"dns"`—at runtime without hardcoding every type in the scheduler.

### What is the difference between the native DNS monitor and the Globalping DNS monitor?

The **native DNS monitor** (`DnsMonitorType` in [`server/monitor-types/dns.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/dns.js)) performs DNS resolution locally on the Uptime Kuma server using Node.js `dns/promises`. The **Globalping DNS monitor** (`GlobalpingMonitorType` subtype in [`server/monitor-types/globalping.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/globalping.js)) sends DNS queries through the Globalping API, executing the resolution from distributed probes across the global network rather than the local instance.

### How does the Real Browser monitor type work?

The **real-browser** monitor (`RealBrowserMonitorType` in [`server/monitor-types/real-browser-monitor-type.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/real-browser-monitor-type.js)) launches a headless Chromium instance using the **Playwright** automation library. It navigates to the target URL, optionally executes user-defined JavaScript, and validates the presence of specific DOM selectors or keywords. This provides true end-to-end testing that captures JavaScript-rendered content unlike simple HTTP checks.

### Can I create custom monitor types for Uptime Kuma?

Yes, the architecture supports custom monitor types by creating a new JavaScript file in `server/monitor-types/` that exports a class extending `MonitorType` from [`server/monitor-types/monitor-type.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/monitor-type.js). The class must implement the `check(monitor, heartbeat, server)` method to perform the health check and update the heartbeat object. Once the file is added, the monitor type becomes available to the scheduler automatically.