Add comprehensive Uptime Kuma management documentation
Complete documentation for monitor and tag management workflows: New documentation: - README.md: Quick reference and complete workflow guide - TAG_MANAGEMENT.md: Comprehensive tag management strategies - tag_monitor.sh: Quick CLI script to tag monitors Updated documentation: - API.md: Added tag management section with quick reference Coverage: - Adding monitors with tags (complete workflow) - Updating and deleting monitors - Tag management strategies and patterns - Common tagging patterns by service type - Troubleshooting guide - Best practices and maintenance tasks All common operations are now documented with examples.
This commit is contained in:
@@ -0,0 +1,264 @@
|
||||
# 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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
./manage_monitors.py list
|
||||
# Note the ID of your new monitor (e.g., 15)
|
||||
```
|
||||
|
||||
**Step 3: Add tags using Python API**
|
||||
```python
|
||||
#!/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:
|
||||
|
||||
```bash
|
||||
#!/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:**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
./check_tags.py
|
||||
```
|
||||
|
||||
Or check a specific monitor:
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
```python
|
||||
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)
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```python
|
||||
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"
|
||||
Reference in New Issue
Block a user