Metadata-Version: 2.4
Name: runsentry-agent
Version: 1.0.0
Summary: RunSentry Agent - Monitor and track scheduled job executions
Author-email: RunSentry <support@runsentry.io>
License: MIT
Project-URL: Homepage, https://runsentry.io
Project-URL: Documentation, https://docs.runsentry.io
Project-URL: Repository, https://github.com/runsentry/agent
Keywords: monitoring,cron,scheduled-jobs,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: k8s
Requires-Dist: kubernetes>=28.0.0; extra == "k8s"

# RunSentry Agent

The RunSentry agent monitors and tracks scheduled job executions on Linux systems. It discovers cron jobs and Kubernetes CronJobs, tracks their executions, and sends data to the RunSentry backend.

## Features

- 🔍 **Automatic Discovery**: Discovers cron jobs and Kubernetes CronJobs
- 📊 **Execution Tracking**: Tracks job start, finish, duration, and exit codes
- 🔒 **Secure**: Outbound-only HTTPS communication, no inbound ports
- 💾 **Resilient**: Local event buffering for offline operation
- 🚀 **Easy Installation**: One-line installer script

## Quick Start

### Installation

**One-line installation with automatic registration:**

```bash
RUNSENTRY_TOKEN=your_token_here curl -fsSL https://get.runsentry.io/install.sh | bash
```

The installer will:
1. Validate Linux OS and Python 3.10+
2. Create isolated virtual environment at `/opt/runsentry/venv`
3. Install the RunSentry agent package
4. Automatically register agent with backend (if `RUNSENTRY_TOKEN` is provided)
5. Install and enable systemd service
6. Start the service automatically if registration succeeds

**Installation without token (for later registration):**

```bash
curl -fsSL https://get.runsentry.io/install.sh | bash

# Register manually later
RUNSENTRY_TOKEN=xxx /opt/runsentry/venv/bin/runsentry register --backend-url https://api.runsentry.io
systemctl start runsentry-agent
```

**With custom backend URL:**

```bash
RUNSENTRY_TOKEN=xxx RUNSENTRY_BACKEND_URL=https://api.example.com curl -fsSL https://get.runsentry.io/install.sh | bash
```

## Usage

### Daemon Mode

The agent runs as a systemd service automatically after installation:

```bash
# Check status
systemctl status runsentry-agent

# View logs
journalctl -u runsentry-agent -f

# Restart
systemctl restart runsentry-agent
```

The daemon will:
- Discover jobs on startup and periodically (every hour)
- Flush buffered events to the backend (every minute)
- Run continuously until stopped

### Execution Wrapper

Wrap your cron jobs to track executions:

```bash
# Instead of:
0 * * * * /path/to/script.sh

# Use:
0 * * * * /opt/runsentry/venv/bin/runsentry exec /path/to/script.sh
```

The wrapper will:
- Send execution start event
- Execute your command
- Capture exit code and duration
- Send execution finish event
- Works even if backend is temporarily unavailable (events are buffered)

### CLI Commands

The agent exposes three commands:

- **`runsentry daemon`** - Run agent daemon (used by systemd service)
- **`runsentry exec <command>`** - Execute and track a job execution
- **`runsentry register`** - Register agent with backend (internal, used by install.sh)

**Note:** The `register` command is internal and used automatically by `install.sh`. Manual registration can be done if needed:
```bash
/opt/runsentry/venv/bin/runsentry register --token xxx --backend-url https://api.runsentry.io
```

## Configuration

Configuration is stored at `/etc/runsentry/config.yaml`:

```yaml
agent_id: agt_123
backend_url: https://api.runsentry.io
token: <signed-jwt>
agent_name: prod-vm-1
```

## Discovery

The agent automatically discovers:

- **Linux Cron**: 
  - User crontab (`crontab -l`)
  - System crontab (`/etc/crontab`)
  - Cron.d directory (`/etc/cron.d/*`)

- **Kubernetes CronJobs**:
  - Requires `kubernetes` Python package
  - Uses in-cluster config or kubeconfig
  - Discovers all namespaces

## Systemd Service

The agent runs as a systemd service:

```bash
# Check status
systemctl status runsentry-agent

# View logs
journalctl -u runsentry-agent -f

# Restart
systemctl restart runsentry-agent

# Stop
systemctl stop runsentry-agent
```

## Upgrading

Upgrade the agent package manually:

```bash
source /opt/runsentry/venv/bin/activate
pip install --upgrade runsentry-agent
systemctl restart runsentry-agent
```

Configuration is preserved during upgrades.

## Development

### Local Development Setup

```bash
# Clone repository
git clone https://github.com/runsentry/agent.git
cd agent

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Install with Kubernetes support
pip install -e ".[k8s]"
```

### Running Tests

```bash
pytest
```

## Architecture

The agent operates in two modes:

1. **Daemon Mode**: Continuous background process for discovery and sync
2. **Exec Mode**: Wrapper for individual job executions

All communication is outbound-only HTTPS to the RunSentry backend.

## Security

- ✅ Outbound-only HTTPS
- ✅ Token-based authentication
- ✅ Signed agent JWT
- ✅ Read-only discovery permissions
- ✅ No inbound ports
- ✅ Secure configuration file (600 permissions)

## Requirements

- Python 3.10+
- Linux (Ubuntu, Debian, RHEL, etc.)
- Network access to RunSentry backend
- Root or sudo access for installation

## Troubleshooting

### Agent not discovering jobs

- Check that cron jobs exist: `crontab -l`
- Verify agent has read permissions to `/etc/crontab` and `/etc/cron.d/`
- Check daemon logs: `journalctl -u runsentry-agent`

### Events not reaching backend

- Check network connectivity to backend URL
- Verify agent token is valid
- Check buffered events: `/var/lib/runsentry/buffer/events.jsonl`
- Review logs for errors

### Service won't start

- Check Python version: `python3 --version`
- Verify virtual environment exists: `/opt/runsentry/venv`
- Check systemd logs: `journalctl -u runsentry-agent`

## License

MIT License

## Support

For issues and questions:
- Documentation: https://docs.runsentry.io
- Support: support@runsentry.io

