# 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"