I’ve written about how railroad syntax diagrams (see here) are great for helping write code (or configuration files). Following the track through the diagram will give you the correct statement syntax, and generally, the diagrams don’t require you to jump around like BNF or eBNF representations.
As you may have seen, I’m currently writing a book on Fluent Bit, and guess what? We’re on the Stream Processor chapter. Looking broaching the use of syntax, it just felt right to have a railroad diagram. As the diagram is fairly large, it won’t print well, so here are the diagrams.
The master content is in GitHub here. If you want a quick reference to how the diagrams work, check here.
Stream Processor Configuration
While Fluent Bit’s core syntax is pretty straightforward, the syntax for the stream processing is a bit more complex, with a strong resemblance to SQL. As SQL is declarative in nature and can contain iterative and nested elements, RailRoad diagrams can really help.
The original BNF definition of the Stream SQL syntax is here.
Fluent Bit Configuration RailRoad Diagrams
When it comes to the core configuration files, RailRoad diagrams aren’t as effective because the configuration is more declarative in nature. But we’ve tried to capture the core essence here. The only issue is that representing things like the use of @include, which can show up in most parts of the file – arent so easy, and a list of attributes for each possible standard plugin would make the diagram enormously large and unwieldy.
We know there are gaps in the current diagrams, which will be addressed. Including:
- YAML format
- @include
- We should show that environment variables can be references as attributes
- A better way to show the required indentation and line separation
Phil (aka MP3Monster)'s Blog 
You must be logged in to post a comment.