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:

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

# Custom port
aveloxis serve --monitor :8082

# 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 paginated table shows the queue ordered by collecting first, then queued, then priority and due date.

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

Search and pagination (v0.18.6)

The dashboard supports a search box and per-page selector above the table, and Prev/Next controls below it. Query parameters:

Parameter

Default

Notes

page

1

1-based page number

page_size

100

Rows per page; capped at 500

q

(empty)

Case-insensitive substring match on repo_owner or repo_name

Example: http://localhost:5555/?q=apache&page_size=200&page=2.

Before v0.18.6 the dashboard rendered every row on a single page and issued one SELECT per row to look up repo metadata (N+1). On large fleets that combination (1) made the page slow to render during active collection and (2) competed with collection workers for pgx pool connections. The dashboard now issues three queries total per refresh (QueueStats, ListQueuePage, and a batched GetReposBatch + GetRepoStatsBatch), regardless of fleet size.

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.

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

Response:

[
  {
    "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.

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

Response:

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

POST /api/prioritize/{repoID}

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

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:

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

Or redirect:

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

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

# /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:

journalctl -u aveloxis -f

Checking status via psql

You can also query the queue directly in PostgreSQL:

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