[Docs] Improve Linux tuning guidance for high-concurrency MQTT workloads
- Dominant language
- HTML
- Stars
- 10
- Forks
- 9
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 10
Description
Part of #66.
## User need
Operators running large numbers of MQTT connections need reliable guidance for Linux connection tracking, sockets, file descriptors, backlog, memory, and safe rollback.
Search evidence suggests that queries such as `nf_conntrack_max`, `MQTT broker Linux tuning`, and `high-concurrency MQTT` are discovery paths to this topic. The existing `/docs/admin_guide/tuning/os_tuning_linux/` page is the natural place to improve rather than creating a separate marketing landing page.
## Proposed documentation
Discuss the technical outline on the public dev list and improve the official guide with community review:
- Symptoms and diagnostics for `nf_conntrack: table full`.
- How to inspect `nf_conntrack_count`, `nf_conntrack_max`, buckets, memory pressure, and packet loss.
- A capacity-sizing method tied to MQTT TCP connections, NAT/network topology, host memory, and a documented safety margin.
- Persistent configuration examples for supported Linux distributions and Kubernetes nodes.
- Related socket backlog, ephemeral ports, file descriptors, TCP keepalive, and TIME_WAIT considerations.
- Explicit cautions against copying a single “maximum” value without measurement.
- Reproducible test methodology and links to Apache BifroMQ observability metrics.
- Troubleshooting questions based on real operator needs.
Use authoritative Linux kernel and upstream distribution documentation. Clearly distinguish upstream kernel behavior, general operational advice, and Apache BifroMQ-specific observations.
## Page presentation and internal links
- Use a direct title/H1 such as “Linux tuning for high-concurrency MQTT workloads”.
- Explain early how the guidance applies to an Apache BifroMQ deployment.
- Link naturally from installation, Kubernetes deployment, high availability, observability, and test-report pages where it helps users complete a task.
- Include safety, rollback, version, and assumption information alongside commands.
Shared website-readiness checks are handled in #71.
## Acceptance criteria
- [ ] Scope and technical recommendations receive public community review.
- [ ] Kernel facts cite authoritative upstream sources.
- [ ] Commands are tested and include safety/rollback notes.
- [ ] BifroMQ-specific recommendations include versions, assumptions, and reproducible evidence.
- [ ] Relevant documentation paths link to the guide naturally.
- [ ] GSC/Bing discovery and ASF Matomo usage (if enabled) are reviewed after a complete 28-day period alongside issue/support feedback.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with /docs/admin_guide/tuning/os_tuning_linux/ and the public dev list discussion; compare the requested Linux and Kubernetes-node topics with authoritative kernel and upstream distribution sources. Validate commands and reproducible methodology, then check installation, Kubernetes deployment, high availability, observability, and test-report links. Done means reviewed, cited, versioned guidance with safety and rollback notes and completed acceptance checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes, linux
- Domain
- documentation, infrastructure, networking
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100