Maintenance, Graph Query, and Overview¶

This page describes three admin tools for platform operators:

The Admin item shows only for platform administrators. Overview is the first page that the Admin menu opens.

Permissions¶

Graph Query has no permission. Only a platform administrator (is_admin) can use it.

Maintenance¶

A maintenance operation does one job for every project, in all organizations. Reindex Search works on every searchable node instead of every project. For example, Sync Commits & Tags backfills the commit history of each project. Use these operations after an upgrade, after an incident, or to repair data.

The page has two tabs: Operations and Activity.

Operations¶

The descriptions come from the code. Imbi runs no operation on a schedule, Close Out Stuck Deployments included. Deployments stay pending until an administrator runs it. See Run an operation.

The Report ... (dry run) operations change nothing. Run them before the operation that they report on, and read the activity log.

Run an operation¶

1. Open Admin > Global Admin > Maintenance.
2. On the Operations tab, click Run in the row of the operation.
3. Read the dialog. The operation runs across everything that it covers, in all organizations. It can put a large load on Imbi and on the remote systems.
4. Click Run.

The row shows the progress while the run continues. To stop a run, click Cancel. Imbi starts no more projects. The projects in progress finish. Imbi does not undo the projects that are done.

How a run works:

• Imbi puts the ids of all projects in a Valkey set. Each imbi-api instance takes ids from the set and does the work. Without Valkey, Imbi refuses the run with 503.
• One run of an operation can be active at a time. A second Run gets 409.
• When a remote system rate-limits Sync Commits & Tags or Sync Pull Requests, Imbi puts the project back in the set and pauses the operation until the limit resets. The activity log shows these projects as deferred.
• If all the instances stop during a run, the run shows as abandoned after 12 hours.
• The row shows the result of the last run for 7 days.

A run has one of these states: idle, running, completed, cancelled, or abandoned.

Imbi does not run an operation on a schedule by itself. The API endpoint is POST /maintenance/operations/{slug}/run, and the caller needs admin:maintenance:manage. A scheduled task cannot call it today: a service_account task runs as the scheduler's own account, and the imbi-scheduler role does not have that permission. A delegated_user task does not run yet. See Scheduler tasks.

Activity log¶

The Activity tab shows what each run did. Imbi keeps one row for each project attempt, with the outcome:

Use the outcome filter and the operation filter to narrow the list. Open a row to see the details that the operation recorded for that attempt.

The log is in the ClickHouse table maintenance_log. Imbi deletes rows after 90 days. The rows go through Iggy, so a new run can take some seconds to show.

Graph Query¶

Graph Query runs a Cypher query against the Apache AGE graph and shows the result.

1. Open Admin > Global Admin > Graph Query.
2. Type a query in the editor. The query must have a RETURN clause. Imbi uses the names in the last RETURN as the columns.
3. Press Ctrl+Enter (⌘ Enter on macOS) to run it.

Example:

MATCH (p:Project)-[:OWNED_BY]->(t:Team)
RETURN p.name AS project, t.name AS team
LIMIT 25

The result has three views: Graph, Table, and RAW. Click a node or a relationship in the graph to see its properties.

The side panel has two parts:

• Schema lists the node labels, the relationship types, and the property keys, with counts.
• History lists your earlier queries. Click one to load it into the editor.

When a query fails, Imbi shows the database error, with the line and the column when the database gives them.

AGE does not support every Cypher feature. See the Apache AGE documentation.

Overview¶

Admin > <Org> Admin > Overview shows the state of the platform. It needs admin:dashboard:read.

The Project health bands are:

System health¶

Imbi checks these datastores: PostgreSQL, ClickHouse, Valkey, and Iggy.

Imbi checks the services with a request to the /status endpoint of each. The URL of each service comes from an environment variable of imbi-api:

When a variable is empty, the service shows as down with the detail not configured. The API row is the imbi-api instance that answers the request.

Iggy topics¶

The Iggy topics card has one row for each Iggy topic. Each topic has a sink consumer group, which writes the messages to ClickHouse. See Events.

The dot of each row shows the state:

The card refreshes every 30 seconds. Use the interval menu to change it, from Off to 1h. Click a column name to sort.

Related pages¶

• Scoring Policies
• Project Doctor
• Events
• Operations