Uptime Kuma Monitor Types: Complete Implementation Guide and Architecture

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. 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 orchestrates the execution loop. It dynamically loads the appropriate monitor class based on the monitor.type string stored in the database:

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.

• 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.

• 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.

• 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.

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.

• 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.

• 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.

• grpc (GrpcMonitorType): Performs gRPC health checks using @grpc/grpc-js. Invokes unary methods and validates responses. Found in 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.

• postgres (PostgresMonitorType): Uses pg (node-postgres) driver. Supports custom SQL queries with conditional expression evaluation. Found in server/monitor-types/postgres.js.

• mssql (MssqlMonitorType): Implements Microsoft SQL Server monitoring using the mssql driver. Located in 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.

• redis (RedisMonitorType): Connects via ioredis and sends PING commands. Supports authentication. Located in 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.

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.

• 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.

• smtp (SmtpMonitorType): Validates SMTP server availability using nodemailer. Supports STARTTLS and certificate validation. Optionally sends test emails. Located in server/monitor-types/smtp.js.

• sip-options (SipOptionsMonitorType): Sends SIP OPTIONS requests using sip.js. Validates response codes and body patterns. Found in 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.

• 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.

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.

• 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.

• 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.

Practical Implementation Examples

Adding a TCP Port Monitor via API

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

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.

Configuring an HTTP Monitor with Globalping

For distributed HTTP monitoring using the Globalping network:

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 to build the measurement and validate response codes.

Setting Up Native DNS Resolution

To monitor DNS records using the local resolver:

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, 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 TCPMonitorTypefor"port"orDnsMonitorTypefor"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) 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) 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) 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}