Skip to content

Maintenance (Administration)

OctoPerf offers maintenance tasks that clean up orphaned data: data whose parent is gone, such as the dedicated IPs of a provider that no longer exists. These tasks never run on their own. A platform administrator launches each run from the Maintenance page, chooses whether it deletes anything, then reads its report.

Open the page from the user menu, in the Administration section, between Scheduled Jobs and Workspaces. Only platform administrators can see it.

Maintenance

The page has three parts: the tasks on the left, the reports of their runs in the center, and the Settings panel at the bottom.

Tasks

The left table lists the maintenance tasks:

Task What a run does
orphaned-workspaces Deletes the workspace members whose user account no longer exists, then the workspaces left without any member, with their projects.
orphaned-projects Deletes the projects whose workspace no longer exists.
orphaned-project-entities Deletes what the projects that no longer exist still hold, such as their Virtual Users and scenarios.
orphaned-result-projects Deletes the copies of projects kept with test results when no test result uses them any more, once they are a day old.
reports-of-deleted-results Removes the test results that no longer exist from the reports, so that the members of the project can open these reports again.
orphaned-docker-links Stops sharing a provider with a workspace when no user is a member of both that workspace and the workspace of the provider. A provider always stays in its own workspace.
orphaned-static-ips Deletes the dedicated IPs whose provider no longer exists, and logs each one with its address, region, zone and cloud identifiers, so that you can release it from your cloud account. Run it after orphaned-docker-links, which can delete providers.
  • Point at the name of a task to read what a run of it does.
  • Click a task to show only its reports. Click it again to go back to the reports of every task.
  • Run, shown when you point at a task, opens the settings of a new run: see Run a task.
  • A task that is running shows a spinning icon on its row: point at the icon to read when the run started. Stop then replaces Run: see Stop a run.

Run a task

Point at a task and click Run. A dialog opens with the description of the task and the settings of the run, filled with safe values:

Run a maintenance task

Setting What it does
Mode Dry run, the default, counts what the cleanup would delete and deletes nothing. Delete deletes it.
Max percent The share of the examined items the run may delete, 1 by default, from 0 to 100. When the cleanup finds more, it stops and deletes nothing: its report says Over limit.
Max per second The most items the run deletes per second, 0.5 or more. Leave it empty for no limit.

Click Run to start the task in the background. A run in Delete mode asks you to confirm first. When OctoPerf refuses the run, because the same task is already running for instance, the dialog stays open and says why.

To clean up safely:

  1. Run the task as a Dry run, and read its report: how many items it would delete, and from how many missing parents.
  2. Once the counts look right, run it again in Delete mode, with the same Max percent.
  3. If the report says Over limit and the orphans are expected, after a bulk deletion for instance, run it again with a higher Max percent.

The page does not follow a run by itself: click Refresh to see whether it is still running, and to read its report once it is done.

Stop a run

Point at a running task and click Stop, then confirm. The run stops before its next deletion: what it already deleted stays deleted, and its report says Stopped.

A running task

Reports

The center table lists the last 100 reports, newest first, or the reports of the task you selected. Each run of a task gives one report. Click Refresh to load the latest ones.

Column What it shows
Started When the run started.
Task The task that ran.
Status Completed, Over limit, Stopped or Failed: see below.
Mode Dry run, in blue, when the run only counted. Apply when it changed the data, as a cleanup run in Delete mode does.
Duration How long the run took.
Summary What the run did, in one line. For example, 22 of 26 deleted from 3 gone parents.

What needs your attention

  • Over limit, in orange: the run found more orphans than its Max percent allows, so it deleted nothing. This protects your data when something else went wrong. Read its report, then, if the orphans are expected, run the task again with a higher Max percent.
  • Failed, in red: the run stopped on an error. Point at it to read the error.
  • Stopped, in bold: an administrator stopped the run. What it deleted before is listed in its report.

The number of missing parents behind the orphans tells you where they come from:

  • Many orphans behind few parents usually come from one bulk deletion, such as a removed workspace and everything it held.
  • As many parents as orphans suggests a leak: data that should have been deleted along with its parent, one item at a time. Report it to the OctoPerf support.

Reports are kept 7 days by default. You can change that in the Settings panel.

Open a report

Click a report, or point at it and click Open, to read it in full: the description of the task, the status, Dry run for a run that only counted, when the run started and how long it took, the error of a failed run, then the summary and the details of the run. For a cleanup, the details give one line per kind of data it looked at: what it deleted or would delete, what it spared, and why it stopped.

Maintenance report

Run, at the bottom of the report, opens the dialog of a new run of the same task, filled with the safe values rather than the settings of the run you read. It is greyed out while the task is running.

Settings

The Settings panel holds the settings of the maintenance tasks. It is closed on your first visit: open it with the sliders icon at the bottom of the right toolbar, whose badge gives the number of settings. It opens at the bottom of the page, and your browser remembers whether you left it open and how high.

Settings panel

  • Each setting shows what it changes, its Default and its Value. A value in bold differs from its default.
  • Point at the name of a setting to read its key, the one the REST API and the AI agents use.
  • Point at a setting and click Edit, or click anywhere on its row, to change it. The dialog shows its description and its default value. Enter the new value and click Save, or click Reset to default. A value the setting refuses keeps the dialog open, with the reason under the field.

Edit a setting

The Reset to default button is greyed out while the value is already the default one.

A new value applies at once to every server of the cluster, with no restart. It is stored by OctoPerf, not in the configuration file, so it survives a restart and an upgrade.

Setting What it changes
Maintenance report retention How many days a report is kept: 7 by default, a whole number from 1 to 3650. The older reports are deleted whenever a new report is stored, so a shorter retention takes effect at the next run of a task.

From the REST API

The same actions are available from the REST API, with the API key of a platform administrator. Any other account gets a 403 response.

Request What it does
GET /admin/maintenance The maintenance tasks, each with its name, its description, the defaults a run starts from, and its run in progress, if any.
POST /admin/maintenance/{name}/run Starts the task in the background with the settings in the body. Settings out of range get a 400 response, an unknown task a 404 response, and a task already running a 409 response.
POST /admin/maintenance/{name}/stop Asks the run of the task to stop before its next deletion. A task that is not running gets a 409 response.
GET /admin/maintenance/reports The latest reports, newest first. size sets how many, from 1 to 1000, 100 by default.
GET /admin/maintenance/{name}/reports The latest reports of one task, newest first, with the same size.
GET /admin/settings The settings, each with its key, label, description, value and defaultValue. The retention is maintenance-reports.retention-days.
PUT /admin/settings/{key}?value= Changes one setting and returns it with its new value. A refused value gets a 400 response that says what the setting accepts, an unknown key a 404 response.

The body of a run gives the mode, DRY_RUN or DELETE, and the max percent. Add "maxPerSecond": 2 next to them to limit the pace. For example, to run a dry run of the dedicated IP cleanup:

curl --request POST --header "Authorization: Bearer <apiKey>" \
  --header "Content-Type: application/json" \
  --data '{"@type": "CleanupSettings",
    "policy": {"mode": "DRY_RUN", "maxPercent": 1}}' \
  "https://<your server>/admin/maintenance/orphaned-static-ips/run"

A run returns at once: to follow it, read the tasks or the reports again. Each report gives the task, when it started, how long it took in milliseconds (elapsed), its status (COMPLETED, OVER_LIMIT, STOPPED or FAILED), its mode (DRY_RUN, or APPLY for a run in DELETE mode), the error of a failed run, its summary, and its details in Markdown (markdown). For example, to read the last 10 reports of the dedicated IP cleanup:

curl --get --header "Authorization: Bearer <apiKey>" \
  --data size=10 \
  "https://<your server>/admin/maintenance/orphaned-static-ips/reports"

To keep the reports 30 days:

KEY=maintenance-reports.retention-days
curl --request PUT --header "Authorization: Bearer <apiKey>" \
  --url-query value=30 \
  "https://<your server>/admin/settings/$KEY"

From an AI agent

The MCP server offers the same actions to platform administrators:

  • list_maintenance_tasks lists the tasks, with their description, the settings a run starts from, and their run in progress,
  • run_cleanup_task starts a cleanup with a mode, a max percent and an optional max per second. As a cleanup may delete data, the agent asks you to confirm first,
  • stop_maintenance_task stops a run,
  • list_maintenance_reports reads the reports,
  • list_settings reads the settings, with their current and default values,
  • update_setting changes one, for the whole cluster. The agent asks you to confirm first too.