How Monitor Groups Organize Monitors in Uptime Kuma: Database Design and Implementation

Uptime Kuma bundles individual service monitors into logical monitor groups using a many-to-many database relationship and a specialized group monitor type that aggregates the health status of all child services.

Monitor groups in Uptime Kuma serve as the primary organizational layer for managing large infrastructure deployments. By linking monitors to groups through a relational schema and supporting a synthetic monitor type that reports aggregated status, the application enables both logical dashboard organization and high-level service health monitoring.

Database Architecture for Monitor Groups

The relationship between monitors and groups is implemented through a junction table defined in db/knex_init_db.js. The monitor_group table stores monitor_id and group_id as foreign keys, along with a weight field that controls display ordering on status pages.

Additional columns include send_url and custom_url, which are utilized when a monitor is configured as a group-type monitor. This schema allows a single monitor to belong to multiple groups while maintaining sort priority through the weight integer.

Group Model and Public API

The server/model/group.js file defines the Group class, which provides two critical methods for group operations:

• getMonitorList() – Executes a SQL join against the monitor_group table to retrieve all monitors associated with a specific group ID.
• toPublicJSON() – Serializes the group into a public-facing format containing the group's id, name, weight, and an embedded array of child monitors.

The API router in server/routers/api-router.js exposes endpoints that interact with these model methods. Creating a group inserts a record into the group table, while assigning a monitor to a group updates both the monitor.parent field and the monitor_group junction table.

Frontend Integration

The monitor editing interface binds the group relationship through the parent field. In src/pages/EditMonitor.vue, the UI renders a selector populated with existing groups, storing the selected group ID in the monitor's parent property.

When a user saves a monitor with a selected group, the application persists this relationship through the API layer, which updates the database schema accordingly. This allows the monitor to appear within the group's context on both the dashboard and public status pages.

Aggregated Status Monitoring

Uptime Kuma implements a specialized monitor type for groups in server/monitor-types/group.js. This synthetic monitor aggregates the status of all active child monitors to provide a high-level health overview.

The GroupMonitorType.check() method retrieves child monitors using Monitor.getChildren(parentId), then evaluates their last heartbeat status. The aggregation logic reports the worst available status following the hierarchy: UP → PENDING → DOWN.

When children are down or pending, the monitor generates descriptive messages such as:

Child monitors down: Monitor C; pending: Monitor D

This allows operators to treat an entire service stack as a single logical unit while maintaining visibility into individual component failures.

Status Page Rendering

Public status pages leverage the group model to organize displays. In server/model/status_page.js, the rendering logic calls groupBean.toPublicJSON() to embed grouped monitors into the page response.

The monitor_group weight field determines the sort order of monitors within each group section. Real-time updates to group ordering are handled by the socket handler in server/socket-handlers/status-page-socket-handler.js, which manipulates monitor_group rows via SQL when users reorder monitors on the status page.

Summary

• Database Layer: The monitor_group junction table links monitors to groups with ordering weights and optional URL configurations.
• Backend Logic: server/model/group.js provides data retrieval and JSON serialization, while server/monitor-types/group.js implements aggregated health checking.
• Frontend Binding: The parent field in src/pages/EditMonitor.vue connects monitors to their groups in the UI.
• API Surface: REST endpoints in server/routers/api-router.js handle CRUD operations for group assignments.
• Public Display: Status pages render grouped monitors using toPublicJSON() with weight-based sorting.

Frequently Asked Questions

How do I assign an existing monitor to a monitor group?

Send a PUT request to /api/monitor/{id} with a JSON body containing "parent": {group_id}. The API updates the monitor's parent field and the monitor_group junction table to establish the relationship.

What is the difference between a regular monitor and a group-type monitor?

A regular monitor checks a specific endpoint or service directly. A group-type monitor is a synthetic monitor that aggregates the status of all monitors assigned to a specific group, reporting the worst health status (UP → PENDING → DOWN) among its children.

How does Uptime Kuma determine the order of monitors within a group on status pages?

The weight field in the monitor_group junction table controls display ordering. When rendering status pages, the server sorts monitors by this integer value, and real-time reordering operations update these weights via the status page socket handler.

Can a monitor belong to multiple groups simultaneously?

The database schema supports many-to-many relationships through the monitor_group junction table. However, the UI typically manages a single parent relationship per monitor for dashboard organization, while status pages may leverage the junction table for more complex display scenarios.

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