continuwuation/continuwuity
continuwuation/continuwuity
14
77
Fork 85
Code Issues 107 Pull requests 42 Releases 27 Packages 3 Activity Actions 5

WIP: docs: Add performance tuning guide #1498

Draft
stratself wants to merge 1 commit from stratself/continuwuity:stratself/docs-perf-tuning into main
pull from: stratself/continuwuity:stratself/docs-perf-tuning
merge into: continuwuation:main
Conversation 5 Commits 1 Files changed 1 +80
stratself commented 2026-03-06 11:04:10 +00:00
Contributor
Copy link

This PR adds a page for performance tuning. As it is WIP feedback is highly appreciated. If you have any other perf tuning tips, please share :)

Will update _meta.json later after future rebasing. DNS tuning will be another page and in another PR.

Some todos:

  • Add section for maxperf builds
  • Sysctl tunings should be recommended, and link to good guides on it. Find good guides.

Some questions to answer, ideally with real-world examples:

  • Should *_capacity_mb params be documented? Or is tweaking the modifier good enough
  • Any helpful gains from rocksdb_parallelism_threads and rocksdb_direct_io tunings?
  • Does sender_workers help with anything?

Pull request checklist:

  • This pull request targets the main branch, and the branch is named something other than
    main.
  • I have written an appropriate pull request title and my description is clear.
  • I understand I am responsible for the contents of this pull request.
  • I have followed the contributing guidelines:
This PR adds a page for performance tuning. As it is WIP feedback is highly appreciated. If you have any other perf tuning tips, please share :) Will update `_meta.json` later after future rebasing. DNS tuning will be another page and in another PR. Some todos: - [ ] Add section for maxperf builds - [ ] Sysctl tunings should be recommended, and link to good guides on it. Find good guides. Some questions to answer, ideally with real-world examples: - Should `*_capacity_mb` params be documented? Or is tweaking the modifier good enough - Any helpful gains from `rocksdb_parallelism_threads` and `rocksdb_direct_io` tunings? - Does `sender_workers` help with anything? **Pull request checklist:** <!-- You need to complete these before your PR can be considered. If you aren't sure about some, feel free to ask for clarification in #dev:continuwuity.org. --> - [x] This pull request targets the `main` branch, and the branch is named something other than `main`. - [x] I have written an appropriate pull request title and my description is clear. - [x] I understand I am responsible for the contents of this pull request. - I have followed the [contributing guidelines][c1]: - [ ] My contribution follows the [code style][c2], if applicable. - [x] I ran [pre-commit checks][c1pc] before opening/drafting this pull request. - [x] I have [tested my contribution][c1t] (or proof-read it for documentation-only changes) myself, if applicable. This includes ensuring code compiles. - [x] My commit messages follow the [commit message format][c1cm] and are descriptive. - [ ] I have written a [news fragment][n1] for this PR, if applicable<!--(can be done after hitting open!)-->. <!-- Notes on these requirements: - While not required, we encourage you to sign your commits with GPG or SSH to attest the authenticity of your changes. - While we allow LLM-assisted contributions, we do not appreciate contributions that are low quality, which is typical of machine-generated contributions that have not had a lot of love and care from a human. Please do not open a PR if all you have done is asked ChatGPT to tidy up the codebase with a +-100,000 diff. - In the case of code style violations, reviewers may leave review comments/change requests indicating what the ideal change would look like. For example, a reviewer may suggest you lower a log level, or use `match` instead of `if/else` etc. - In the case of code style violations, pre-commit check failures, minor things like typos/spelling errors, and in some cases commit format violations, reviewers may modify your branch directly, typically by making changes and adding a commit. Particularly in the latter case, a reviewer may rebase your commits to squash "spammy" ones (like "fix", "fix", "actually fix"), and reword commit messages that don't satisfy the format. - Pull requests MUST pass the `Checks` CI workflows to be capable of being merged. This can only be bypassed in exceptional circumstances. If your CI flakes, let us know in matrix:r/dev:continuwuity.org. - Pull requests have to be based on the latest `main` commit before being merged. If the main branch changes while you're making your changes, you should make sure you rebase on main before opening a PR. Your branch will be rebased on main before it is merged if it has fallen behind. - We typically only do fast-forward merges, so your entire commit log will be included. Once in main, it's difficult to get out cleanly, so put on your best dress, smile for the cameras! --> [c1]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md [c2]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/docs/development/code_style.mdx [c1pc]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#pre-commit-checks [c1t]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#running-tests-locally [c1cm]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#commit-messages [n1]: https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments
docs: Add initial performance tuning guidance
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Details
Update flake hashes / update-flake-hashes (pull_request) Successful in 1m43s
Details
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m2s
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m31s
Details
2404ddada0
lveneris commented 2026-03-06 11:26:53 +00:00
Contributor
Copy link

Remind me to review this when you're done writing up the other sections pretty please

Remind me to review this when you're done writing up the other sections pretty please
Henry-Hiles requested changes 2026-03-06 17:09:06 +00:00
docs/advanced/performance.md
@ -0,0 +48,4 @@
allow_incoming_typing = false
```
Presence is also considered expensive and is disabled by default. For reference, you can also disable them manually as follows:
Henry-Hiles commented 2026-03-06 17:08:22 +00:00
Contributor
Copy link

Isn't only outgoing presence off by default?

Isn't only outgoing presence off by default?
nex requested changes 2026-03-06 17:20:55 +00:00
nex left a comment
Owner
Copy link

Provisional notes, feel free to disregard if unwanted

Provisional notes, feel free to disregard if unwanted
docs/advanced/performance.md
@ -0,0 +1,80 @@
# Performance tuning
While Continuwuity's default config parameters are optimized for a small instance, they would likely need additional modifications to smoothly run in a larger context. This is especially true for homeservers with many users and/or are joined in many large federated rooms, and will increasingly be the case as the Matrix network expands.
nex commented 2026-03-06 17:20:44 +00:00
Owner
Copy link

This isn't necessarily true. You will only need to tune the default parameters if your hardware configuration does not scale with your server size (works in both directions - throwing a supercomputer at a tiny instance will waste resources, while throwing a potato at a moderately sized server will make it choke itself).

This isn't necessarily true. You will only need to tune the default parameters if your hardware configuration does not scale with your server size (works in both directions - throwing a supercomputer at a tiny instance will waste resources, while throwing a potato at a moderately sized server will make it choke itself).
docs/advanced/performance.md
@ -0,0 +19,4 @@
## Changing database compression algorithm
:::warning
This step should be done **before** starting Continuwuity for the first time
nex commented 2026-03-06 17:17:54 +00:00
Owner
Copy link

should -> MUST - afaik the algo can't be changed after init. Also worth mentioning it can't be reversed.

`should` -> `MUST` - afaik the algo *can't* be changed after init. Also worth mentioning it can't be reversed.
docs/advanced/performance.md
@ -0,0 +27,4 @@
```toml
### in continuwuity.toml ###
rocksdb_compression_algo = "lz4"
rocksdb_wal_compression = "none"
nex commented 2026-03-06 17:17:16 +00:00
Owner
Copy link

I'm pretty sure this significantly increases storage usage.

I'm pretty sure this *significantly* increases storage usage.
nex commented 2026-03-06 17:23:08 +00:00
Owner
Copy link

Should *_capacity_mb params be documented? Or is tweaking the modifier good enough

Tweaking the modifier is fine for a guide. Ideally we don't get too nitty-gritty on tuning in the docs otherwise people will break their stuff and make it our problem.

Does sender_workers help with anything?

Since it already scales to the number of available CPUs, not really, especially since senders aren't particularly CPU heavy (in comparison to state resolution etc).

> Should `*_capacity_mb` params be documented? Or is tweaking the modifier good enough Tweaking the modifier is fine for a guide. Ideally we don't get too nitty-gritty on tuning in the docs otherwise people *will* break their stuff and make it our problem. > Does `sender_workers` help with anything? Since it already scales to the number of available CPUs, not really, especially since senders aren't particularly CPU heavy (in comparison to state resolution etc).
spaetz reviewed 2026-03-06 20:00:02 +00:00
docs/advanced/performance.md
@ -0,0 +5,4 @@
This page aims to outline various performance tweaks for Continuwuity and their effects. As always, your mileage may vary according to your setup's specifics. If you have further discussions or recommendations, please share them in the community rooms.
## DNS tuning (recommended)
spaetz commented 2026-03-06 20:00:02 +00:00
First-time contributor
Copy link

A separate DNS tuning guide sounds good, I would still include a paragraph on why that is needed in general in this documente. Something like:
"Matrix homeservers conduct MANY DNS queries, sometimes 10s of thousands within a few minutes. Normal tools, such as system-resolved are not designed for this load, and upstream DNS providers will often rate-limit you for making so many queries."

A separate DNS tuning guide sounds good, I would still include a paragraph on why that is needed in general in this documente. Something like: "Matrix homeservers conduct MANY DNS queries, sometimes 10s of thousands within a few minutes. Normal tools, such as system-resolved are not designed for this load, and upstream DNS providers will often rate-limit you for making so many queries."
👍 1
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Details
Update flake hashes / update-flake-hashes (pull_request) Successful in 1m43s
Details
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m2s
Required
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m31s
Required
Details
This pull request is marked as a work in progress.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u stratself/docs-perf-tuning:stratself-stratself/docs-perf-tuning
git switch stratself-stratself/docs-perf-tuning
Sign in to join this conversation.
Reviewers
No reviewers
Henry-Hiles
nex
Labels
Clear labels   
Blocked

This pull request or issue is currently blocked from being merged/closed

  
Bug

Something isn't working as intended

  
Cherry-picking

Commits picked from other conduit projects

  
Database

This requires or includes changes to the database

  
Dependencies

Something dependency related

  
Dependencies/Renovate

Automatic dependency upgrades by Renovate

  
Difficulty
Easy
Low difficulty to implement - touches few parts of the codebase, low complexity

  
Difficulty
Hard
High difficulty to implement - touches many parts of the codebase, high complexity

  
Difficulty
Medium
Medium difficulty to implement - touches more parts of the codebase, higher complexity

  
Documentation

Improvements or additions to documentation

  
Enhancement

New feature or request

  
Good first issue

Good for newcomers

  
Help wanted

Additional eyes and keyboards are required for this one

  
Inherited

Issues that have been inhereted from the project pre-fork

  
Matrix/Administration

Features pertaining to homeserver administration

  
Matrix/Appservices

Features pertaining to the appservice API

  
Matrix/Auth

Features pertaining to authentication

  
Matrix/Client

Features pertaining to client-to-server interactions

  
Matrix/Core

Issues relating to core matrix functionality, such as state resolution and PDU formats

  
Matrix/E2EE

   
Matrix/Federation

Features pertaining to server-to-server interactions

  
Matrix/Hydra

Issues related to room version 12 and related changes (temporary label)

  
Matrix/MSC

Features pertaining to unstable matrix features

  
Matrix/Media

Features pertaining to media interactions

  
Matrix/T&S

Changes or issues related to trust & safety tooling

  
Meta

Related to housekeeping, maintenance, or other repo-meta.

  
Meta/CI

Issues related to CI changes

  
Meta/Packaging

Packaging

  
Priority
Blocking
This issue is blocking the next release

  
Priority
High
This issue is very important

  
Priority
Low
This issue is of a rather low priority

  
Security

This item is related to general security

  
Status
Confirmed
This issue has enough information and is confirmed

  
Status
Duplicate
This issue or pull request already exists

  
Status
Invalid
This issue doesn't seem right

  
Status
Needs Investigation
This issue needs further investigation

  
Support

Questions or support requests

  
To-Merge

   
Wont fix

This will not be worked on

  
old/ci/cd

Ci/CD

Archived

  
old/rust

Pull requests that update Rust code

Archived

No labels
Blocked
Bug
Cherry-picking
Database
Dependencies
Dependencies/Renovate
Difficulty
Easy
Difficulty
Hard
Difficulty
Medium
Documentation
Enhancement
Good first issue
Help wanted
Inherited
Matrix/Administration
Matrix/Appservices
Matrix/Auth
Matrix/Client
Matrix/Core
Matrix/E2EE
Matrix/Federation
Matrix/Hydra
Matrix/MSC
Matrix/Media
Matrix/T&S
Meta
Meta/CI
Meta/Packaging
Priority
Blocking
Priority
High
Priority
Low
Security
Status
Confirmed
Status
Duplicate
Status
Invalid
Status
Needs Investigation
Support
To-Merge
Wont fix
old/ci/cd
old/rust
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
5 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
continuwuation/continuwuity!1498
No description provided.