docker-infrastructure/uptime-kuma/TAG_MANAGEMENT.md

Tag Management Guide

This guide covers managing tags and tag assignments in Uptime Kuma.

Overview

Tags help organize and categorize monitors. Each monitor can have multiple tags, and you can filter monitors by tags in the web UI.

Current Tag Schema

Service Categories

Tag Name	Color	Use For
hardware	🔴 Red	Physical hardware (fans, sensors)
monitoring	🟠 Orange	Monitoring systems and health checks
application	🔵 Blue	Software applications and services
web	🔷 Cyan	Web services and HTTP endpoints
database	🟣 Purple	Database systems
media	🌸 Pink	Media servers (Plex, etc.)
infrastructure	🟢 Green	Core infrastructure components
storage	🟢 Light Green	Storage systems (NAS, file servers)
virtualization	🟦 Teal	Virtualization platforms (Proxmox)
vm	🔹 Blue Grey	Virtual machines

Common Workflows

Adding a New Monitor with Tags

Step 1: Add the monitor

export UPTIME_KUMA_USERNAME="your_username"
export UPTIME_KUMA_PASSWORD="your_password"

./manage_monitors.py add --name "New Service" --url "https://newservice.com" --type http

Step 2: Note the monitor ID from the output or list

./manage_monitors.py list
# Note the ID of your new monitor (e.g., 15)

Step 3: Add tags using Python API

#!/usr/bin/env python3
from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login("username", "password")

# Add tags to monitor
api.add_monitor_tag(tag_id=3, monitor_id=15, value='')  # application
api.add_monitor_tag(tag_id=4, monitor_id=15, value='')  # web

api.disconnect()

Quick Tag Script

Create a simple script to tag a new monitor:

#!/bin/bash
# tag_monitor.sh - Quick script to tag a monitor
# Usage: ./tag_monitor.sh MONITOR_ID TAG_ID [TAG_ID...]

MONITOR_ID=$1
shift

python3 << EOF
from uptime_kuma_api import UptimeKumaApi
import os

api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login(os.getenv('UPTIME_KUMA_USERNAME'), os.getenv('UPTIME_KUMA_PASSWORD'))

for tag_id in [${@}]:
    try:
        api.add_monitor_tag(tag_id=tag_id, monitor_id=${MONITOR_ID}, value='')
        print(f"✓ Added tag {tag_id} to monitor ${MONITOR_ID}")
    except Exception as e:
        print(f"✗ Failed: {e}")

api.disconnect()
EOF

Usage:

# Tag monitor 15 as application + web
export UPTIME_KUMA_USERNAME="poprhythm"
export UPTIME_KUMA_PASSWORD="your_password"
./tag_monitor.sh 15 3 4

Viewing Tags on a Monitor

./check_tags.py

Or check a specific monitor:

from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login("username", "password")

monitor = api.get_monitor(15)
print(f"Tags: {monitor.get('tags', [])}")

api.disconnect()

Removing a Tag from a Monitor

from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login("username", "password")

# Remove tag_id 3 from monitor 15
api.delete_monitor_tag(tag_id=3, monitor_id=15, value='')

api.disconnect()

Adding New Tag Types

If you need to create a new tag:

from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login("username", "password")

# Create a new tag
result = api.add_tag(name="production", color="#FF5722")
print(f"Created tag with ID: {result['id']}")

api.disconnect()

Tag Assignment Patterns

By Service Type

• Web Services: application + web
• Databases: application + database
• Media Servers: application + media
• Storage Systems: infrastructure + storage
• Virtual Machines: infrastructure + vm
• Hardware Monitoring: hardware + monitoring
• Virtualization Platforms: infrastructure + virtualization

By Environment (if needed)

You can create additional tags for environments:

api.add_tag(name="production", color="#4CAF50")
api.add_tag(name="staging", color="#FFC107")
api.add_tag(name="development", color="#2196F3")

By Priority (if needed)

api.add_tag(name="critical", color="#F44336")
api.add_tag(name="high", color="#FF9800")
api.add_tag(name="normal", color="#4CAF50")
api.add_tag(name="low", color="#9E9E9E")

Complete Example: Adding a New Service

# 1. Add the monitor
./manage_monitors.py add \
  --name "GitLab" \
  --url "https://gitlab.example.com" \
  --type http \
  --interval 60

# 2. List to get the ID
./manage_monitors.py list | grep GitLab
# Output: 16     GitLab     http     https://gitlab.example.com

# 3. Tag it (using Python one-liner)
python3 -c "
from uptime_kuma_api import UptimeKumaApi
import os
api = UptimeKumaApi('https://uptime.kolpacksoftware.com', ssl_verify=False)
api.login(os.getenv('UPTIME_KUMA_USERNAME'), os.getenv('UPTIME_KUMA_PASSWORD'))
api.add_monitor_tag(tag_id=3, monitor_id=16, value='')  # application
api.add_monitor_tag(tag_id=4, monitor_id=16, value='')  # web
api.disconnect()
print('Tagged successfully!')
"

# 4. Verify
./check_tags.py | grep GitLab

Tag Reference Quick Lookup

Tag ID	Tag Name	Common Use
1	hardware	Server fans, sensors
2	monitoring	Health checks
3	application	Any software service
4	web	HTTP/HTTPS services
5	database	PostgreSQL, MySQL, CouchDB, etc.
6	media	Plex, Jellyfin, etc.
7	infrastructure	Core systems
8	storage	NAS, file servers
9	virtualization	Proxmox, ESXi
10	vm	Virtual machine instances

Best Practices

1. Consistent Naming: Use lowercase for tag names
2. Multiple Tags: Apply 2-3 relevant tags per monitor for better organization
3. Color Coding: Use similar colors for related tags (all infrastructure tags are shades of green)
4. Document Custom Tags: If you add custom tags, document them in this file
5. Tag on Creation: Always tag new monitors immediately after creation
6. Regular Audits: Run check_tags.py periodically to find untagged monitors

Troubleshooting

"Tag already exists" Error

This means the tag is already assigned to the monitor. You can safely ignore this.

"Monitor not found"

Double-check the monitor ID with ./manage_monitors.py list.

Session Timeout

If you're tagging many monitors, you may need to reconnect. The API session can timeout after several minutes of inactivity.

View All Tags

from uptime_kuma_api import UptimeKumaApi
api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
api.login("username", "password")
tags = api.get_tags()
for tag in tags:
    print(f"ID {tag['id']}: {tag['name']} ({tag['color']})")
api.disconnect()

Scripts Available

• check_tags.py - View all monitor tag assignments
• add_tags.py - Bulk tag assignment (requires editing for new monitors)
• fix_missing_tags.py - Add specific tags to specific monitors
• TAG_SUMMARY.md - Current tag schema documentation

Web UI Management

For one-off changes, the web UI is often easier:

1. Go to https://uptime.kolpacksoftware.com
2. Click on a monitor to edit it
3. Scroll to the "Tags" section
4. Add/remove tags as needed
5. Click "Save"