# Monitoring

Aveloxis includes a built-in web dashboard and REST API for monitoring collection progress.

---

## Dashboard

### URL and configuration

The monitoring dashboard is served by `aveloxis serve` at the address specified by the `--monitor` flag:

```bash
# Default: http://localhost:5555
aveloxis serve --monitor :5555

# Custom port
aveloxis serve --monitor :8080

# Bind to all interfaces (for remote access)
aveloxis serve --monitor 0.0.0.0:5555
```

Open your browser to `http://localhost:5555` (or your configured address).

The dashboard auto-refreshes every 10 seconds.

---

### Queue statistics

The top of the dashboard shows aggregate queue statistics:

| Metric | Description |
|---|---|
| **Total** | Total number of repos in the queue |
| **Queued** | Repos waiting to be collected |
| **Collecting** | Repos currently being collected by a worker |

---

### Repo status table

Below the statistics, a table shows every repo in the queue with:

| Column | Description |
|---|---|
| **Repo** | Repository owner/name |
| **Status** | Current status: `queued`, `collecting`, `completed`, `failed` |
| **Priority** | Queue priority (lower = collected sooner) |
| **Due Time** | When the repo is next eligible for collection |
| **Last Run** | Results of the most recent collection (entity counts, errors) |
| **Actions** | Boost button to push the repo to the front |

---

### Boost button

Each queued repo has a **Boost** button that pushes it to the top of the queue. Clicking Boost:

1. Sets the repo's priority to 0
2. Sets its due time to now
3. The scheduler will collect it next (after the current in-progress repos finish)

This is equivalent to running `aveloxis prioritize <url>` from the CLI.

---

## REST API endpoints

The monitoring server exposes a REST API for programmatic access.

### `GET /api/queue`

Returns the full queue state as JSON.

```bash
curl http://localhost:5555/api/queue
```

Response:

```json
[
  {
    "repo_id": 42,
    "repo_git": "https://github.com/chaoss/augur",
    "status": "collecting",
    "priority": 100,
    "due_at": "2026-04-05T12:00:00Z",
    "last_collected_at": "2026-04-04T12:00:00Z"
  },
  ...
]
```

### `GET /api/stats`

Returns aggregate queue statistics.

```bash
curl http://localhost:5555/api/stats
```

Response:

```json
{
  "queued": 150,
  "collecting": 4,
  "total": 200
}
```

### `POST /api/prioritize/{repoID}`

Pushes a repo to the top of the queue by its `repo_id`.

```bash
curl -X POST http://localhost:5555/api/prioritize/42
```

Returns 200 on success.

---

## Log output

Aveloxis logs to standard output. The verbosity is controlled by the `log_level` setting in `aveloxis.json`.

### INFO level (default)

At the default INFO level, you see per-repo progress:

```
INFO  starting collection for chaoss/augur (repo_id=42)
INFO  prelim: URL OK, no redirect
INFO  phase1: staged 234 issues, 189 PRs, 1042 events, 523 messages
INFO  phase2: processed 234 issues, 189 PRs, 1042 events, 523 messages
INFO  phase3: facade: 15234 commits from git log
INFO  phase4: resolved 892/1204 commit authors
INFO  phase5: enriched 45 contributor emails
INFO  phase6: analysis: 312 dependencies, 287 libyear entries, 1523 repo_labor rows
INFO  completed chaoss/augur in 2m34s
```

### DEBUG level

At DEBUG level, you see individual API calls, staging writes, contributor resolution details, and SQL operations. Useful for troubleshooting but very verbose.

### Where logs go

Logs are written to standard output (`stdout`). To save logs to a file:

```bash
aveloxis serve --monitor :5555 2>&1 | tee aveloxis.log
```

Or redirect:

```bash
aveloxis serve --monitor :5555 > aveloxis.log 2>&1 &
```

For production deployments, consider using a process manager like `systemd` that captures output automatically:

```ini
# /etc/systemd/system/aveloxis.service
[Unit]
Description=Aveloxis Collection Service
After=postgresql.service

[Service]
Type=simple
User=aveloxis
WorkingDirectory=/opt/aveloxis
ExecStart=/usr/local/bin/aveloxis serve --workers 4 --monitor :5555
ExecStop=/usr/local/bin/aveloxis stop
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target
```

Logs can then be viewed with:

```bash
journalctl -u aveloxis -f
```

---

## Checking status via psql

You can also query the queue directly in PostgreSQL:

```sql
-- Queue summary
SELECT status, COUNT(*)
FROM aveloxis_ops.collection_queue
GROUP BY status;

-- Currently collecting
SELECT q.repo_id, r.repo_owner, r.repo_name, q.locked_at
FROM aveloxis_ops.collection_queue q
JOIN aveloxis_data.repos r ON r.repo_id = q.repo_id
WHERE q.status = 'collecting';

-- Repos with errors
SELECT q.repo_id, r.repo_owner, r.repo_name, q.last_error
FROM aveloxis_ops.collection_queue q
JOIN aveloxis_data.repos r ON r.repo_id = q.repo_id
WHERE q.last_error IS NOT NULL AND q.last_error != '';

-- Staging table size (should be near 0 when not collecting)
SELECT COUNT(*) AS staged_rows
FROM aveloxis_ops.staging;
```

---

## Next steps

- [Scaling](scaling.md) -- worker count and throughput tuning
- [Troubleshooting](troubleshooting.md) -- diagnosing common issues
- [Commands Reference](commands.md) -- CLI command details