Developer guide for beginners on contributing to Fluent Bit
Assuming you have some basic knowledge of C, this guide should help you understand how to make code changes to Fluent Bit.
Libraries
Most external libraries are embedded in the project in the /lib folder. To keep its footprint low and make cross-platform builds simple, Fluent Bit attempts keep its dependency graph small.
The external library you are mostly likely to interact with is msgpack.
For cryptographic support, Fluent Bit uses the system installed version of OpenSSL. Please make sure to install openssl libraries and headers before building Fluent Bit.
Memory Management
When you write Fluent Bit code, you will use Fluent Bit's versions of the standard C functions for working with memory:
flb_malloc()
- equivalent tomalloc
, allocates memory.flb_calloc()
- equivalent tocalloc
, allocates memory and initializes it to zero.flb_realloc()
- equivalent torealloc
.flb_free()
- equivalent tofree
, releases allocated memory.
Note that many types have a specialized create and destroy function. For example, flb_sds_create()
and flb_sds_destroy()
(more about this in the next section).
Strings
Fluent Bit has a stripped down version of the popular SDS string library. See flb_sds.h for the API.
In general, you should use SDS strings in any string processing code. SDS strings are fully compatible with any C function that accepts a null-terminated sequence of characters; to understand how they work, see the explanation on Github.
HTTP Client
Fluent Bit has its own network connection library. The key types and functions are defined in the following header files:
The following code demonstrates making an HTTP request in Fluent Bit:
An flb_upstream
structure represents a host/endpoint that you want to call. Normally, you'd store this structure somewhere so that it can be re-used. An flb_upstream_conn
represents a connection to that host for a single HTTP request. The connection structure should not be used for more than one request.
Linked Lists
Fluent Bit contains a library for constructing linked lists- cfl_list. The type stores data as a circular linked list.
The cfl_list.h
header file contains several macros and functions for use with the lists. The example below shows how to create a list, iterate through it, and delete an element.
Message Pack
Fluent Bit uses msgpack to internally store data. If you write code for Fluent Bit, it is almost certain that you will interact with msgpack.
Fluent Bit embeds the msgpack-c library. The example below shows manipulating message pack to add a new key-value pair to a record. In Fluent Bit, the filter_record_modifier plugin adds or deletes keys from records. See its code for more.
Please also check out the message pack examples on the msgpack-c GitHub repo.
Plugin API
Each plugin is a shared object which is loaded into Fluent Bit using dlopen and dlsym.
Input
The input plugin structure is defined in flb_input.h. There are a number of functions which a plugin can implement, most only implement cb_init
, cb_collect
, and cb_exit
.
The "dummy"
input plugin is very simple and is an excellent example to review to understand more.
Note that input plugins can use threaded mode if the flag FLB_INPUT_THREADED
is provided. To enable threading in your plugin, add the FLB_INPUT_THREADED
to the set of flags
when registering:
Filter
The structure for filter plugins is defined in flb_filter.h. Each plugin must implement cb_init
, cb_filter
, and cb_exit
.
The filter_record_modifier is a good example of a filter plugin.
Note that filter plugins can not asynchronously make HTTP requests. If your plugin needs to make a request, add the following code when you initialize your flb_upstream
:
Output
Output plugins are defined in flb_output.h. Each plugin must implement cb_init
, cb_flush
, and cb_exit
.
The stdout plugin is very simple; review its code to understand how output plugins work.
Development Environment
Fluent Bit provides a standalone environment for development. Developers who use different OS or distributions can develop on a simple, common stack. The development environment provides the required libraries and tools for you.
Development environments provided for
Testing
During development, you can build Fluent Bit as follows:
Note that Fluent Bit uses Cmake 3 and on some systems you may need to invoke it as cmake3
.
To enable the unit tests run:
Internal tests are for the internal libraries of Fluent Bit. Runtime tests are for the plugins.
You can run the unit tests with make test
, however, this is inconvenient in practice. Each test file will create an executable in the build/bin
directory which you can run directly. For example, if you want to run the SDS tests, you can invoke them as follows:
Need more help?
The best way to learn how Fluent Bit code works is to read it. If you need help understanding the code, reach out to the community, or open a PR with changes that are a work in progress.
Last updated