Service Monitor Skill Skill

Service Monitor Skill

This skill enables management of the service-monitor application running at http://raspberrypi.local:8000.

Overview

The service-monitor is a FastAPI application that monitors the health of various services by periodically checking their health endpoints. It tracks service status (UP, DOWN, DEGRADED, UNKNOWN) and provides notifications when services change state.

API Base URL

http://raspberrypi.local:8000

Key Concepts

Service Statuses

UP: Service is healthy and responding as expected
DOWN: Service is unreachable or timing out
DEGRADED: Service is responding but not with expected status/content
UNKNOWN: Service has never checked in or status is uncertain

Service Types

Services (/services/*): Runtime status of monitored services
- Tracks current health state
- Receives check-ins from services
- Can be manually removed
Monitored Services (/monitored-services/*): Configuration for automatic monitoring
- Defines health check URLs and intervals
- Automatically polls services and updates their status
- Persistent configuration stored in monitored_services.json

Common Operations

1. Get All Services Status

Get the current status of all services being monitored:

curl -s http://raspberrypi.local:8000/services | jq .

Response: Array of ServiceInfo objects with:

service_name: Name of the service
status: Current status (up/down/degraded/unknown)
last_check_in: ISO timestamp of last check
message: Status message
metadata: Additional metadata (health_url, response_time, etc.)
check_in_count: Total number of check-ins

2. Get Specific Service Status

curl -s http://raspberrypi.local:8000/services/{service_name} | jq .

3. Get Services by Status

Filter services by their current status:

curl -s http://raspberrypi.local:8000/services/status/{status} | jq .

Where {status} is one of: up, down, degraded, unknown

4. Remove a Service

Remove a service from monitoring (this removes runtime status, not configuration):

curl -X DELETE http://raspberrypi.local:8000/services/{service_name}

5. List Monitored Services Configuration

Get all configured monitored services:

curl -s http://raspberrypi.local:8000/monitored-services | jq .

Response: Object with:

success: Boolean
services: Array of MonitoredService configurations
total: Number of configured services

6. Get Specific Monitored Service Configuration

curl -s http://raspberrypi.local:8000/monitored-services/{service_name} | jq .

7. Add or Update Monitored Service

Add a new service to be monitored automatically:

curl -X POST http://raspberrypi.local:8000/monitored-services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "health_url": "http://localhost:3000/health",
    "check_interval_seconds": 60,
    "timeout_seconds": 10,
    "expected_status_code": 200,
    "enabled": true,
    "check_response_body": false,
    "expected_body_content": null
  }'

MonitoredService Schema:

name (required): Unique service name
health_url (required): HTTP/HTTPS URL to check
check_interval_seconds (default: 60): How often to check
timeout_seconds (default: 10): Request timeout
expected_status_code (default: 200): Expected HTTP status for healthy service
enabled (default: true): Whether monitoring is enabled
check_response_body (default: false): Validate response body
expected_body_content (optional): Expected substring in response body

8. Update Monitored Service Configuration

curl -X PUT http://raspberrypi.local:8000/monitored-services/{service_name} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "health_url": "http://localhost:3000/health",
    "check_interval_seconds": 30,
    "timeout_seconds": 5,
    "expected_status_code": 200,
    "enabled": true,
    "check_response_body": false,
    "expected_body_content": null
  }'

Note: The name in the request body must match {service_name} in the URL.

9. Remove Monitored Service

Remove a service from automatic monitoring configuration:

curl -X DELETE http://raspberrypi.local:8000/monitored-services/{service_name}

This will:

Stop the automatic health checking
Remove the service from configuration file
Not remove the service's current status from /services

10. Manually Trigger Health Check

Immediately check the health of a monitored service:

curl -X POST http://raspberrypi.local:8000/monitored-services/{service_name}/check

Response:

{
  "success": true,
  "service_name": "my-service",
  "status": "up",
  "message": "Health check passed (200)",
  "metadata": {
    "health_url": "http://localhost:3000/health",
    "http_status_code": "200",
    "response_time_ms": "45.23"
  }
}

11. Get Notification History

View notification history for all services:

curl -s http://raspberrypi.local:8000/notifications/history | jq .

12. Check Service Monitor Health

Check if the service-monitor itself is healthy:

curl -s http://raspberrypi.local:8000/health | jq .

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-23T20:00:00Z",
  "uptime_seconds": 3600.5,
  "monitored_services": 5
}

Usage Guidelines

When using this skill:

Always use jq for formatting JSON responses for better readability
Check monitored services first to see what's configured
Use /services for current status, /monitored-services for configuration
Add services to monitored-services for automatic health checking
Handle errors gracefully - API returns appropriate HTTP status codes
Use manual checks (/monitored-services/{name}/check) for immediate verification

Example Workflows

Add a New Service to Monitor

Check if service already exists:

curl -s http://raspberrypi.local:8000/monitored-services/my-service

If not found, add it:

curl -X POST http://raspberrypi.local:8000/monitored-services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "health_url": "http://localhost:3000/health",
    "check_interval_seconds": 60,
    "timeout_seconds": 10,
    "expected_status_code": 200,
    "enabled": true
  }'

Verify it's being monitored:

curl -s http://raspberrypi.local:8000/services/my-service | jq .

Check Service Health Status

Get all services and their status:

curl -s http://raspberrypi.local:8000/services | jq '.[] | {name: .service_name, status: .status, message: .message}'

Get only problematic services:

curl -s http://raspberrypi.local:8000/services/status/down | jq .
curl -s http://raspberrypi.local:8000/services/status/degraded | jq .

Update Service Configuration

Get current configuration:

curl -s http://raspberrypi.local:8000/monitored-services/my-service | jq .service

Update with new settings:

curl -X PUT http://raspberrypi.local:8000/monitored-services/my-service \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "health_url": "http://localhost:3000/health",
    "check_interval_seconds": 30,
    "timeout_seconds": 10,
    "expected_status_code": 200,
    "enabled": true
  }'

Remove a Service

Stop monitoring (removes from configuration):

curl -X DELETE http://raspberrypi.local:8000/monitored-services/my-service

Optionally, remove current status:

curl -X DELETE http://raspberrypi.local:8000/services/my-service

Error Handling

The API uses standard HTTP status codes:

200: Success
201: Created (for new check-ins)
204: No Content (successful deletion)
400: Bad Request (invalid parameters)
404: Not Found (service doesn't exist)
422: Validation Error (invalid request body)
500: Internal Server Error

Always check the response status and handle errors appropriately.

Integration Notes

The service-monitor runs on raspberrypi.local:8000
Configuration is persisted in monitored_services.json at the project root
Web dashboard available at http://raspberrypi.local:8000/
API documentation at http://raspberrypi.local:8000/docs
Service automatically checks for "stale" services that haven't checked in
Notifications are sent when services change state (if configured)

Agent Skills: Service Monitor Skill

Install this agent skill to your local

Skill Files