Rsyslog Documentation Enters a New Era with AI-First Strategy
TL;DR: We are rolling out a major documentation overhaul for rsyslog, powered by an AI-first strategy. This is the next step after our 2024 announcement on documentation and AI. At that time, AI tools were not yet ready for large-scale improvements, but with recent advances, we’ve accelerated our work. The result: a much more accessible, modern, and maintainable documentation set.
Looking Back: The 2024 Starting Point
In 2024, we published “Documentation Improvement and AI” — our first public statement about modernizing rsyslog’s documentation with AI assistance.
Back then, AI tooling wasn’t mature enough for the scale and complexity of the rsyslog project. We made small steps, but much of the work remained manual and time-consuming.
Fast forward to 2025: AI-assisted authoring has dramatically improved. It is now capable of producing high-quality drafts, validating examples, and suggesting structured improvements. Combined with our own expertise and review processes, we can finally tackle the deep modernization we envisioned.
What’s New?
1. A New “Getting Started” Guide
We’ve rebuilt the onboarding experience with a structured, easy-to-follow guide aimed at both sysadmins and DevOps engineers. The guide avoids legacy syntax, uses modern RainerScript, and adds inline comments to explain why a configuration snippet is written the way it is.
2. Modern Configuration Examples
The configuration/examples.rst page has been rewritten from the ground up. All examples now use list-based templates and modern rule syntax, with clear annotations. This makes it far easier to adapt snippets for your own environment.
3. Visual Message Flow
We’ve introduced Mermaid diagrams to explain how messages move through inputs, rulesets, and actions. These diagrams make it much easier for new users to visualize rsyslog’s internal flow.
4. Focus on RainerScript
While rsyslog remains backward-compatible with sysklogd-style and $-prefixed legacy syntax, we now officially recommend RainerScript for all new configurations. Legacy styles are documented for maintenance purposes but are no longer the default.
5. AI-Assisted CI for Documentation
We have integrated automated checks for syntax errors, broken references, and content drift into the documentation pipeline. AI-based reviews also assist with style and clarity checks on new contributions.
Why This Took Time
Our primary goal was not just to refresh the documentation but to create a sustainable workflow. We needed:
- A strategy for transitioning old pages and templates without breaking URLs.
- A docs-as-code approach that integrates directly into our GitHub CI.
- Confidence in AI’s output, with human review for correctness and clarity.
The result is a documentation foundation that will scale as rsyslog evolves.
What’s Next?
- More Tutorials: Practical, validated guides for real-world use cases (e.g., TLS forwarding, Elasticsearch, Kafka pipelines).
- Legacy Migration Guide: Helping users convert old sysklogd-style configs to RainerScript.
- Community Feedback: GitHub Discussions and “Edit on GitHub” links to simplify user contributions.
Ongoing Revamp: The documentation overhaul is just starting. Much legacy content remains and will be revised step by step. Expect continuous improvements as we modernize this large body of material.
Acknowledging Our Roots
Rsyslog builds on a rich history that started with Eric Allman’s BSD syslogd (1983), passed through sysklogd, and has grown into today’s high-performance logging framework. This long history explains why multiple configuration syntaxes exist — but modern deployments are all about RainerScript, which combines clarity and power for today’s complex logging needs.
Get Involved
You can explore the updated docs here: rsyslog documentation.
If you have feedback or ideas, join the discussion on GitHub Discussions or simply suggest improvements directly via the “Edit on GitHub” links.