feat: system service (aka systemd/ windows service) monitor #6488

iotux · 2025-12-13T07:37:34Z

❗ Important Announcements

Click here for more details:

⚠️ Please Note: We do not accept all types of pull requests, and we want to ensure we don’t waste your time. Before submitting, make sure you have read our pull request guidelines: Pull Request Rules

🚫 Please Avoid Unnecessary Pinging of Maintainers

We kindly ask you to refrain from pinging maintainers unless absolutely necessary. Pings are for critical/urgent pull requests that require immediate attention.

📋 Overview

What problem does this pull request address?
- Currently, Uptime Kuma lacks a generic way to monitor local services or custom scripts on the host machine. While there are specific monitors for databases, Docker, etc., there is no general-purpose monitor to check the status of other services (like systemd services) or the output of custom health check scripts. This has been a requested feature in the community (e.g., in issue Monitor for Linux systemd services #1677), but previous proposals for dedicated monitors (like a systemd monitor) were turned down due to concerns about complexity and "clutter".
- This PR aims to address this need by introducing a flexible and simple monitor type that doesn't add significant complexity to the UI.
What features or functionality does this pull request introduce or enhance?

New 'Local Service' Monitor Type:
- Adds a new monitor type that can execute any shell command on the host machine.
- The monitor's status is determined by checking if the command's output contains an "Expected Output" string. If the expected output is left empty, the monitor's status is determined by the command's exit code (0 for "Up", non-zero for "Down").
- This allows for a wide range of monitoring scenarios, from checking systemd services to running custom scripts or even checking remote services via ssh.
Bug Fix for Prometheus Errors:
- This PR also fixes a bug where adding a new tag to any monitor would cause Prometheus to throw an Error: Added label "X" is not included in initial labelset. The fix re-initializes Prometheus metrics when a new tag is added, so a server restart is no longer required.
Bug Fix for Tag UI:
- A minor bug where the UI was not updated immediately after adding/deleting a tag has also been fixed. This bug was discovered during development. It has later been reported as "Tags is not saved if you dont save 2 time" Tags is not saved if you dont save 2 time #6476

Relates to Monitor for Linux systemd services #1677
Resolves Tags is not saved if you dont save 2 time #6476

🛠️ Type of change

🐛 Bugfix (a non-breaking change that resolves an issue)
✨ New feature (a non-breaking change that adds new functionality)
⚠️ Breaking change (a fix or feature that alters existing functionality in a way that could cause issues)
🎨 User Interface (UI) updates // Added page for Local Service Monitor
📄 New Documentation (addition of new documentation)
📄 Documentation Update (modification of existing documentation)
📄 Documentation Update Required (the change requires updates to related documentation)
🔧 Other (please specify):

Disclaimer

This development has been done entirely by the Gemini CLI LLM, patience and carefully crafted prompts by an 80 year old developer, who has shaking hands and a brain that thinks that the current task is better left to a professional that doesn't ask for food or other unreasonable requirements.

📄 Checklist

📷 Screenshots or Visual Changes

UI Modifications: Highlight any changes made to the user interface.
Before & After: Include screenshots or comparisons (if applicable).

Event	Before	After
`UP`
`DOWN`
Certificate-expiry
Testing

server/monitor-types/local-service.js

louislam · 2025-12-13T08:07:39Z

New 'Local Service' Monitor Type

Need discussion on how to design it properly, directly execute a command, will end up becoming the recent Next.js RCE issue.

Bug Fix for Prometheus Errors:
Bug Fix for Tag UI:

Please create 2 & 3 in separate pull requests.

This adds a new monitor type to check local services by executing a shell command. It also includes fixes for Prometheus errors when adding new tags and for the UI not updating when tags are changed.

CommanderStorm

overall, looks like a promising start.
There is some unrelated code which needs moving to other PRs, but that should be easy to remove.

I have two requests:

could you add a very simple testcase that only executes in CI, so we all are sure that this code works in the future (even if new functionality gets added)
could you make this a non-docker-only monitor (calling it in docker does not quite make senese). I think tailscale was similar.
I think this will only work on linux right, so we need to also restrict to this.

CommanderStorm · 2025-12-14T16:48:45Z

server/monitor-types/local-service.js

+                // systemctl is-active exits with 0 if the service is active,
+                // and a non-zero code if it is inactive, failed, or not found.
+                if (error) {
+                    heartbeat.status = DOWN;


otherwise retrys don't work

Suggested change

heartbeat.status = DOWN;

server/monitor-types/local-service.js

CommanderStorm · 2025-12-14T16:53:07Z

server/monitor-types/local-service.js

+        // This is the name of the service to check e.g. "nginx.service"
+        const serviceName = monitor.local_service_name;


nit: please inline serviceName, as this way I think the code is more clear.

CommanderStorm · 2025-12-14T16:53:42Z

server/prometheus.js

     * @returns {Promise<void>}
     */
    static async init() {
+        PrometheusClient.register.clear();


does not seem related

Suggested change

PrometheusClient.register.clear();

Agreed. This looks like a leftover from my local debugging to prevent duplicate registration errors during hot-reloads. It is definitely not needed for production and I will remove it

CommanderStorm · 2025-12-14T16:54:00Z

server/server.js

+                await Prometheus.init();
+


does not seem related

Suggested change

await Prometheus.init();

Agreed. This was likely leftover debug code intended to force a metric refresh, but it is too aggressive/destructive for production as it clears the global register. I have removed it

CommanderStorm · 2025-12-14T16:54:40Z

server/server.js

+                await server.sendUpdateMonitorIntoList(socket, monitorID);
+


does not seem related

Suggested change

await server.sendUpdateMonitorIntoList(socket, monitorID);

CommanderStorm · 2025-12-14T16:56:00Z

src/pages/EditMonitor.vue

                                        </option>
-
+                                        <option value="local-service">
+                                            {{ $t("Local Service") }}


Please name the monitor Systemd Service instead as it is a bit unclear what a local service is otherwise.

I am seriously considering to extend this monitor to support Windows Services as well (using PowerShell's 'Get-Service'). Because of this hybrid support, 'Systemd Service' would be too specific. I believe that 'Local Service' or 'System Service' fits best as it implies checking the underlying OS service manager (systemd for Linux, SCM for Windows).

"System service" if you add windows support, otherwise "Systemd service" 👍🏻

src/pages/EditMonitor.vue

CommanderStorm · 2025-12-14T16:57:59Z

src/pages/EditMonitor.vue

+                                    <label for="local-service-name" class="form-label">{{ $t("Service Name") }}</label>
+                                    <input id="local-service-name" v-model="monitor.local_service_name" type="text" class="form-control" required placeholder="nginx.service">
+                                    <div class="form-text">
+                                        {{ $t("localServiceDescription") }}


lets add here (via i18n-t) how to debug this monitor.
This way it is much clearer what this monitor does.

server/monitor-types/local-service.js

louislam · 2025-12-15T06:36:18Z

I am not so familiar with Linux distros, but I have seen some Linux distros don't have systemctl/systemd.

May need a better name instead of "Local Service".

iotux · 2025-12-15T11:58:18Z

I am not so familiar with Linux distros, but I have seen some Linux distros don't have systemctl/systemd.
May need a better name instead of "Local Service".

Systemd is used by Ubuntu, Debian, CentOS, RedHat, Fedora, SUSE to name the most known. Those systems covers the vast majority of the server OS market.

To keep the PR clean and maintainable, I propose we stick to Systemd for Linux and later PowerShell for Windows.

Chosing 'Local Service' or 'System Service' is a matter or taste. My personal preference would be 'System Service'.

CommanderStorm · 2025-12-15T14:14:06Z

server/monitor-types/local-service.js

+                // 1. Capture the raw output (prioritize stderr for errors)
+                let output = (stderr || stdout || "").toString().trim();
+
+                // 2. Truncate if too long to ~200 chars
+                if (output.length > 200) {
+                    output = output.substring(0, 200) + "...";
+                }
+
+                if (error) {
+                    // stderr often contains useful info like "service not found"
+                    // Use the truncated output, or a default fallback if empty
+                    heartbeat.msg = stderr || stdout || `Service '${monitor.local_service_name}' is not running.`;


Suggested change

// 1. Capture the raw output (prioritize stderr for errors)

let output = (stderr || stdout || "").toString().trim();

// 2. Truncate if too long to ~200 chars

if (output.length > 200) {

output = output.substring(0, 200) + "...";

}

if (error) {

// stderr often contains useful info like "service not found"

// Use the truncated output, or a default fallback if empty

heartbeat.msg = stderr || stdout || `Service '${monitor.local_service_name}' is not running.`;

// stderr often contains useful info like "service not found"

let output = (stderr || stdout || "").toString().trim();

if (output.length > 200) {

output = output.substring(0, 200) + "...";

}

if (error) {

heartbeat.msg = output || `Service '${monitor.local_service_name}' is not running.`;

iotux · 2025-12-15T16:41:55Z

PR Update Notice
Update: Windows Support & Renaming

Based on the feedback and the cross-platform nature of this feature, I have expanded the scope and finalized the implementation:

Renamed to "System Service": Changed the monitor name from "Local Service" to "System Service" to be OS-agnostic (supports both systemd and Windows Service Manager).

Added Windows Support: The monitor now auto-detects the OS. On Windows, it uses powershell (via Get-Service) to check status, while maintaining systemctl for Linux.

Added debug instructions with platform-specific commands.

Verification:

Verified manually on Linux

I don't have Windows. Hence, I need someone to voluntarily test on a Windows platform

CommanderStorm · 2025-12-15T17:22:07Z

Would writing a testcase for this be possible?
I also don't have windows, but if there were a test I am fine with not manually testing this.

…ver.js

louislam reviewed Dec 13, 2025

View reviewed changes

server/monitor-types/local-service.js Outdated Show resolved Hide resolved

louislam marked this pull request as draft December 13, 2025 08:07

iotux added 10 commits December 14, 2025 16:33

Fixed Promotheus issue related to adding tags (louislam#6476)

d6c4eea

Fix for issue louislam#6476

14f9f12

Reverted previous change

883083f

feat: Add 'local service' monitor type

7461bd2

This adds a new monitor type to check local services by executing a shell command. It also includes fixes for Prometheus errors when adding new tags and for the UI not updating when tags are changed.

Replaced some tabs

3b9c553

Fix: Linting errors and typo

9a2b058

Removed temporary block from vite.config.js

8e93a1d

Moved Local Service to General Monitor Type

1220160

Fixed indent issues

2ffc06d

Simplified and secured Local Service monitor

d76ce4e

iotux force-pushed the feature/local-service-monitor branch from 07f47b6 to d76ce4e Compare December 14, 2025 15:39

CommanderStorm requested changes Dec 14, 2025

View reviewed changes

CommanderStorm added the pr:please address review comments this PR needs a bit more work to be mergable label Dec 14, 2025

iotux added 4 commits December 15, 2025 13:58

Minor local-service cleanup

96e8268

Removed leftover from debugging

a293020

Removed leftovers from testing/debugging

9a0b6a5

Minor i18n changes

7a0a85c

CommanderStorm reviewed Dec 15, 2025

View reviewed changes

iotux added 2 commits December 15, 2025 15:14

Minor i18n changes

9befa8d

Cleaned up some comments

fe50adb

iotux marked this pull request as ready for review December 15, 2025 14:34

iotux added 4 commits December 15, 2025 16:27

Added Windows Service Monitor & changed local to systen

0f951ef

Rename 'Local Service' monitor to 'System Service'

6940241

Added db migration file

e579846

Added db migration file

4a9fac5

Added db migration file

dc0fad4

iotux closed this Dec 15, 2025

iotux reopened this Dec 15, 2025

CommanderStorm added looking-for-testers and removed pr:please address review comments this PR needs a bit more work to be mergable labels Dec 15, 2025

iotux added 2 commits December 16, 2025 05:29

Completed missing name change

fd1583a

i18n and styling fixes

0dda5c3

iotux mentioned this pull request Dec 17, 2025

feat: add platform/arch information to sendInfo #6497

Open

11 tasks

github-actions bot added the needs:resolve-merge-conflict label Dec 17, 2025

CommanderStorm changed the title ~~Feature/local service monitor & issue #6476 fix~~ feat: system service (aka systemd/ windows service) monitor Dec 17, 2025

Resolve merge conflict in server/server.js and server/uptime-kuma-ser…

77d0e73

…ver.js

github-actions bot removed the needs:resolve-merge-conflict label Dec 17, 2025

		// This is the name of the service to check e.g. "nginx.service"
		const serviceName = monitor.local_service_name;

Uh oh!

feat: system service (aka systemd/ windows service) monitor #6488

Are you sure you want to change the base?

feat: system service (aka systemd/ windows service) monitor #6488

Conversation

iotux commented Dec 13, 2025

❗ Important Announcements

🚫 Please Avoid Unnecessary Pinging of Maintainers

📋 Overview

🛠️ Type of change

Disclaimer

📄 Checklist

📷 Screenshots or Visual Changes

Uh oh!

Uh oh!

louislam commented Dec 13, 2025

Uh oh!

CommanderStorm left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

louislam commented Dec 15, 2025

Uh oh!

iotux commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iotux commented Dec 15, 2025

Uh oh!

CommanderStorm commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CommanderStorm left a comment •

edited

Loading

iotux commented Dec 15, 2025 •

edited

Loading