-
Notifications
You must be signed in to change notification settings - Fork 466
GSoC 2019 Proposal: Improve Developer Guide by Implementing New Modules (kmranrg)
A good documentation allows the reader to know about the specifications and working of a product. So, it is very important to prepare and maintain a good product documentation which covers all the technical and non-technical aspects from root level. It should prepare in such a lucid way that the reader gets complete information about the product.
So, the mission of this project is to improve the GitBook of syslog-ng by adding sections dedicated to various types of plugins found in syslog-ng. This will also attract new contributors to syslog-ng.
A summary of the different types of plugins in syslog-ng: what they are and how they are used.
This source driver reads preexisting log messages from a text file. Each time syslog-ng is run, static-file() goes to the beginning of the specified file, reads lines/messages inside until it reaches EOF, and then it terminates. So, it differs from the standard file() driver in that it reads messages already in a text file, rather than wait for new messages to come in.
This will be useful for testing. When designing some other plugin and wishing to test it, rather than manually entering log messages, or even relying on an external script, the messages can simply be placed in a static text file and read each time with static-file().
So why not just implement this as an option or a flag for the existing file() driver? To me, their purposes are different enough (this one being for testing, the other for actual use), and their architectural differences I imagine significant enough (since this one purposely avoids remembering file names and positions between runs), that it makes sense for static-file() to be its own separate plugin.
This driver will have far fewer options and flags than file() to save time, but enough to show how they work.
Implementations of source driver plugins vary drastically. However, they all need to be integrated into syslog-ng. And so, that will be the focus of this section of the GitBook chapter.
This parser separates the elements of messages consisting of an ordered list and places them into corresponding macros. This is best explained by an example:
"1. Cat 2. Dog 3. Log" → ${List1}=="Cat" && ${List2}=="Dog" && ${List3}=="Log"
This parser will feature some flexibility in the "delimiter" used:
"a) Emacs b) Vim c) Ed" → ${ListA}=="Emacs" && ${ListB}=="Vim" && ${ListC}=="Ed"
This parser differs from the csv-parser() in that the delimiters are ordered and therefore non-static.
This section of the GitBook chapter will explain how parsers are implemented and how they work with options and macros.
This filter function filters log messages by their MSG character count. It can filter by length > min or length < max or min < length < max, depending on the arguments passed in.
The functionality of length() could, of course, always have been achieved by using match(). But so could almost any type of filtering, regex being as powerful as it is! Only, power does not mean ease of use, and so this function aims to provide a more user friendly way of filtering messages by length—an alternative to tinkering with regex.
This section of the GitBook chapter will show how to implement a filter function and work with function parameters.
This template function takes in a RAWMSG macro—a whole log message—that complies with the IETF-syslog protocol, and transforms it to comply with the BSD-syslog protocol. Data will likely be lost. A possibility is placing the parts of the IETF message HEADER that the BSD standard does not support into the MSG part of BSD message.
This will provide backward compatibility for the newer standard. (Although in truth I imagine that if there ever were a need for a function like this, it would have already been made.)
This section of the GitBook chapter will detail how to implement a template function and also highlight some of the differences between the two syslog protocols.
From the last year, I have been practicing data structures and algorithms in C programming language. So, I can say I have a good understanding of this language.
From last August, I have been doing a Nanodegree on Machine Learning from Udacity in which I did some projects like Predicting Boston Housing Prices, Finding Donors For Charity ML etc. I have also made some Android applications like Sprinkler Music Player, IPU Syllabus etc. which are available on Google Play Store.
I have read through the syslog-ng OSE Administration Guide and have a solid high-level understanding of how syslog-ng works. I still need to grasp the codebase and learn how to implement the various types of plugins. (If only there were a guide for this!)
Actually, I am also preparing for GRE Examination. So, I have good writing skills. Apart from this, I am very passionate about writing. I won't say I use much heavy English words but yeah, I can still write well. In terms of Technical Writing, I like to use snippets for writing codes. I also won the Smart India Hackathon 2018 held by Govt. of India. In that, my team also had to prepare a good documentation of our software.
I have also commented on README.md file of syslog-ng for making performing some minor changes: #2608
I will work 40 hours a week.
Familiarise myself with the codebase; learn how to create the various types of plugins.
Complete static-file() and source driver GitBook section.
Complete ordered-parser() and parser GitBook section.
Complete length() and filter function GitBook section.
Complete IETF-to-BSD() and template function GitBook section.
Complete GitBook chapter introduction; buffer.
Github: github.com/kmranrg
Email: kmranrg@gmail.com
Phone: +91 9983436229
I will be available from, at latest, 12 p.m. IST onwards everyday, but can start my days earlier if needed.