> For the complete documentation index, see [llms.txt](https://docs.cstplus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cstplus.org/documentation/troubleshooting/performance-issues.md). # Performance Issues ### High CPU usage CST+ is designed to be lightweight at runtime. If CPU is consistently high, identify what is causing it: ```bash top -b -n 1 | head -30 ``` {% tabs %} {% tab title="ffmpeg during render" %} Render is the intentionally heavy step. High CPU during a render is normal and expected. It will drop back to near-zero once the render finishes and the channel starts looping. If you need to render without affecting running channels, limit concurrent renders in **Settings > Rendering > Max concurrent renders**. {% endtab %} {% tab title="ffmpeg during playback" %} Each on-air channel runs one ffmpeg process for the HLS loop. This should use 1-2% CPU per channel. If a loop process is using significantly more, the rendered reel may be malformed. Click **Re-render** on the affected channel to rebuild it. {% endtab %} {% tab title="Ad transcoding" %} SSAI transcodes ad creatives on demand. If many breaks are firing at the same time across multiple channels, CPU can spike. This is temporary and resolves once creatives are cached. If it is a recurring issue, pre-warm the cache by triggering a test break outside of peak hours. {% endtab %} {% endtabs %} *** ### High RAM usage Expected per-component RAM usage: | Component | Typical usage | | ---------------------------- | ------------- | | `cstplus-control` | \~80-150 MB | | `cstplus-edge` | \~60-120 MB | | `cstplus-web` | \~50-80 MB | | Each on-air channel (ffmpeg) | \~54 MB | If total usage is significantly higher than this, check for memory leaks in logs or restart services one at a time to isolate the cause. {% hint style="info" %} RAM usage grows gradually if you have many long-running viewer sessions accumulated in memory. The edge flushes sessions to the database periodically. Restarting `cstplus-edge` clears in-memory sessions (they are already persisted to SQLite). {% endhint %} *** ### Disk filling up Three things consume disk space: | What | Where | How to manage | | ------------------- | ------------------------ | ----------------------------------------------------------------------------------- | | Source content | Your content folders | Delete unused files via File Manager | | Rendered reels | `/opt/cstplus/rendered/` | Automatically replaced on re-render; old reels are cleaned up | | HLS segments | `/opt/cstplus/hls/` | Managed automatically; segment count controlled by `hls_list_size` in Settings | | Backups | `/opt/cstplus/backups/` | Keep last 5 by default (`CSTPLUS_KEEP_BACKUPS`); delete old ones manually if needed | | Viewer session logs | SQLite DB | Set retention in **Settings > General > Session retention days** | {% hint style="warning" %} If disk fills completely, on-air channels will crash because ffmpeg cannot write new HLS segments. Set up a disk usage alert before this happens. {% endhint %} Check current disk usage: ```bash df -h /opt/cstplus du -sh /opt/cstplus/*/ ``` *** ### Slow admin panel The admin panel is a React SPA served locally. If it feels slow: 1. **Check server CPU and RAM** on the Dashboard system meters. If the server is under load from rendering, the panel response may be slower. 2. **Check your browser network tab** for slow API calls. If `/api/system` is consistently slow, the SQLite database may need a vacuum: ```bash sqlite3 /opt/cstplus/data/cstplus.db "VACUUM;" ``` 3. **Check the web service logs** for errors: ```bash journalctl -u cstplus-web -n 50 ``` *** ### Many channels, limited resources If you are running a large number of channels on a smaller server: * Stagger renders: do not render all channels at once. Use **Settings > Rendering > Max concurrent renders** to cap at 1 or 2. * Each channel needs \~54 MB RAM for the loop. 10 channels need roughly 540 MB just for ffmpeg processes. * Monitor network bandwidth: each 720p channel delivers roughly 2-4 Mbps to viewers. Calculate your total peak bandwidth needs before scaling. {% hint style="success" %} If you are hitting the limits of a single server, fleet mode (adding edge nodes) solves the bandwidth bottleneck without needing a larger primary. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cstplus.org/documentation/troubleshooting/performance-issues.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.