Logs & Monitoring

runnem provides comprehensive logging and monitoring capabilities through GNU screen sessions and a robust log management system. Each service runs in its own screen session, and logs are automatically managed with rotation and compression.

Viewing Logs

View logs for a specific service:

runnem log api

This will:

1. Attach to the service's screen session
2. Show the service's output in real-time
3. Allow you to scroll through the logs
4. Press Ctrl+A then D to detach from the logs

Log Management

runnem automatically manages logs with the following features:

• Logs are stored in ~/.runnem/logs/{project_name}/{service}.log
• Automatic log rotation when files exceed 100MB
• Compressed archives of old logs are kept (up to 3 backups)
• Logs are preserved even when services are stopped
• Failed service logs are saved for troubleshooting

Example log directory structure:

~/.runnem/logs/
└── myproject/
    ├── api.log
    ├── api.20240301-120000.gz
    ├── api.20240301-110000.gz
    ├── frontend.log
    └── frontend.20240301-120000.gz

Monitoring Service Status

Check the status of all services:

runnem list

This shows:

• Which services are running
• Service URLs (if defined)
• Service status (Running/Stopped)
• Log file locations for each service

Health Checks

For services with defined URLs, runnem performs health checks in two scenarios:

1. When starting dependent services:

services:
  api:
    command: npm run dev
    url: http://localhost:3000/health  # Health check endpoint
    depends_on: ["database"]  # Will check database's URL before starting

2. When verifying service startup:

services:
  api:
    command: npm run dev
    url: http://localhost:3000/health  # Will check this URL after starting

In both cases, runnem will:

1. Wait for the URL to be accessible
2. Retry up to 3 times
3. Show status messages during checks

Troubleshooting

If a service fails to start, runnem provides:

1. Startup error logs:

runnem log api

2. Persistent error logs in the service's log file at ~/.runnem/logs/{project_name}/{service}.log

3. Service status information:

runnem list

Next Steps

• Configuration - See how to configure your services with a runnem YAML
• CLI Reference - Browse through the list of options in Runnem's command-line interface
• Why Runnem? - Learn the philosophy and motivation behind the tool