mirror of
https://github.com/element-hq/synapse
synced 2024-08-20 07:20:20 +00:00
Instead of having admins poke into the database directly. Can currently run jobs to populate stats and to populate the user directory.
109 lines
2.4 KiB
Markdown
109 lines
2.4 KiB
Markdown
# Background Updates API
|
|
|
|
This API allows a server administrator to manage the background updates being
|
|
run against the database.
|
|
|
|
## Status
|
|
|
|
This API gets the current status of the background updates.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
GET /_synapse/admin/v1/background_updates/status
|
|
```
|
|
|
|
Returning:
|
|
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"current_updates": {
|
|
"<db_name>": {
|
|
"name": "<background_update_name>",
|
|
"total_item_count": 50,
|
|
"total_duration_ms": 10000.0,
|
|
"average_items_per_ms": 2.2,
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
`enabled` whether the background updates are enabled or disabled.
|
|
|
|
`db_name` the database name (usually Synapse is configured with a single database named 'master').
|
|
|
|
For each update:
|
|
|
|
`name` the name of the update.
|
|
`total_item_count` total number of "items" processed (the meaning of 'items' depends on the update in question).
|
|
`total_duration_ms` how long the background process has been running, not including time spent sleeping.
|
|
`average_items_per_ms` how many items are processed per millisecond based on an exponential average.
|
|
|
|
|
|
## Enabled
|
|
|
|
This API allow pausing background updates.
|
|
|
|
Background updates should *not* be paused for significant periods of time, as
|
|
this can affect the performance of Synapse.
|
|
|
|
*Note*: This won't persist over restarts.
|
|
|
|
*Note*: This won't cancel any update query that is currently running. This is
|
|
usually fine since most queries are short lived, except for `CREATE INDEX`
|
|
background updates which won't be cancelled once started.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
POST /_synapse/admin/v1/background_updates/enabled
|
|
```
|
|
|
|
with the following body:
|
|
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
`enabled` sets whether the background updates are enabled or disabled.
|
|
|
|
The API returns the `enabled` param.
|
|
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
There is also a `GET` version which returns the `enabled` state.
|
|
|
|
|
|
## Run
|
|
|
|
This API schedules a specific background update to run. The job starts immediately after calling the API.
|
|
|
|
|
|
The API is:
|
|
|
|
```
|
|
POST /_synapse/admin/v1/background_updates/start_job
|
|
```
|
|
|
|
with the following body:
|
|
|
|
```json
|
|
{
|
|
"job_name": "populate_stats_process_rooms"
|
|
}
|
|
```
|
|
|
|
The following JSON body parameters are available:
|
|
|
|
- `job_name` - A string which job to run. Valid values are:
|
|
- `populate_stats_process_rooms` - Recalculate the stats for all rooms.
|
|
- `regenerate_directory` - Recalculate the [user directory](../../../user_directory.md) if it is stale or out of sync.
|