C Library API
Fluent Bit library is written in C language and can be used from any C or C++ application. Before digging into the specification it is recommended to understand the workflow involved in the runtime.
Fluent Bit runs as a service, meaning that the API exposed for developers provide interfaces to create and manage a context, specify inputs/outputs, set configuration parameters and set routing paths for the event/records. A typical usage of the library involves:
- Create library instance/context and set properties.
- Enable input plugin(s) and set properties.
- Enable output plugin(s) and set properties.
- Start the library runtime.
- Optionally ingest records manually.
- Stop the library runtime.
- Destroy library instance/context.
Starting from Fluent Bit v0.9, there is only one data type exposed by the library, by convention prefixed with flb_.
Type | Description |
|---|---|
flb_ctx_t | Main library context. It aims to reference the context returned by flb_create(); |
As described earlier, the first step to use the library is to create a context of it, for the purpose the function flb_create() is used.
Prototype
flb_ctx_t *flb_create();
Return Value
On success, flb_create() returns the library context; on error, it returns NULL.
Usage
flb_ctx_t *ctx;
ctx = flb_create();
if (!ctx) {
return NULL;
}
Using the flb_service_set() function is possible to set context properties.
Prototype
int flb_service_set(flb_ctx_t *ctx, ...);
Return Value
On success it returns 0; on error it returns a negative number.
Usage
The flb_service_set() allows to set one or more properties in a key/value string mode, e.g:
int ret;
ret = flb_service_set(ctx, "Flush", "1", NULL);
The above example specified the values for the properties Flush , note that the value is always a string (char *) and once there is no more parameters a NULL argument must be added at the end of the list.
When built, Fluent Bit library contains a certain number of built-in input plugins. In order to enable an input plugin, the function flb_input() is used to create an instance of it.
For plugins, an instance means a context of the plugin enabled. You can create multiples instances of the same plugin.
Prototype
int flb_input(flb_ctx_t *ctx, char *name, void *data);
The argument ctx represents the library context created by flb_create(), then name is the name of the input plugin that is required to enable.
The third argument data can be used to pass a custom reference to the plugin instance, this is mostly used by custom or third party plugins, for generic plugins passing NULL is OK.
Return Value
On success, flb_input() returns an integer value >= zero (similar to a file descriptor); on error, it returns a negative number.
Usage
int in_ffd;
in_ffd = flb_input(ctx, "cpu", NULL);
A plugin instance created through flb_input(), may provide some configuration properties. Using the flb_input_set() function is possible to set these properties.
Prototype
int flb_input_set(flb_ctx_t *ctx, int in_ffd, ...);
Return Value
On success it returns 0; on error it returns a negative number.
Usage
The flb_input_set() allows to set one or more properties in a key/value string mode, e.g:
int ret;
ret = flb_input_set(ctx, in_ffd,
"tag", "my_records",
"ssl", "false",
NULL);
The argument ctx represents the library context created by flb_create(). The above example specified the values for the properties tag and ssl, note that the value is always a string (char *) and once there is no more parameters a NULL argument must be added at the end of the list.
The properties allowed per input plugin are specified on each specific plugin documentation.
When built, Fluent Bit library contains a certain number of built-in output plugins. In order to enable an output plugin, the function flb_output() is used to create an instance of it.
For plugins, an instance means a context of the plugin enabled. You can create multiples instances of the same plugin.
Prototype
int flb_output(flb_ctx_t *ctx, char *name, void *data);
The argument ctx represents the library context created by flb_create(), then name is the name of the output plugin that is required to enable.
The third argument data can be used to pass a custom reference to the plugin instance, this is mostly used by custom or third party plugins, for generic plugins passing NULL is OK.
Return Value
On success, flb_output() returns the output plugin instance; on error, it returns a negative number.
Usage
int out_ffd;
out_ffd = flb_output(ctx, "stdout", NULL);
A plugin instance created through flb_output(), may provide some configuration properties. Using the flb_output_set() function is possible to set these properties.
Prototype
int flb_output_set(flb_ctx_t *ctx, int out_ffd, ...);
Return Value
On success it returns an integer value >= zero (similar to a file descriptor); on error it returns a negative number.
Usage
The flb_output_set() allows to set one or more properties in a key/value string mode, e.g:
int ret;
ret = flb_output_set(ctx, out_ffd,
"tag", "my_records",
"ssl", "false",
NULL);
The argument ctx represents the library context created by flb_create(). The above example specified the values for the properties tag and ssl, note that the value is always a string (char *) and once there is no more parameters a NULL argument must be added at the end of the list.
The properties allowed per output plugin are specified on each specific plugin documentation.
Once the library context has been created and the input/output plugin instances are set, the next step is to start the engine. When started, the engine runs inside a new thread (POSIX thread) without blocking the caller application. To start the engine the function flb_start() is used.
Prototype
int flb_start(flb_ctx_t *ctx);
Return Value
On success it returns 0; on error it returns a negative number.
Usage
This simple call only needs as argument ctx which is the reference to the context created at the beginning with flb_create():
int ret;
ret = flb_start(ctx);
To stop a running Fluent Bit engine, we provide the call flb_stop() for that purpose.
Prototype
int flb_stop(flb_ctx_t *ctx);
The argument ctx is a reference to the context created at the beginning with flb_create() and previously started with flb_start().
When the call is invoked, the engine will wait a maximum of five seconds to flush buffers and release the resources in use. A stopped context can be re-started any time but without any data on it.
Return Value
On success it returns 0; on error it returns a negative number.
Usage
int ret;
ret = flb_stop(ctx);
A library context must be destroyed after is not longer necessary, note that a previous flb_stop() call is mandatory. When destroyed all resources associated are released.
Prototype
void flb_destroy(flb_ctx_t *ctx);
The argument ctx is a reference to the context created at the beginning with flb_create().
Return Value
No return value.
Usage
flb_destroy(ctx);
There are some cases where the caller application may want to ingest data into Fluent Bit, for this purpose exists the function flb_lib_push().
Prototype
int flb_lib_push(flb_ctx_t *ctx, int in_ffd, void *data, size_t len);
The first argument is the context created previously through flb_create(). in_ffd is the numeric reference of the input plugin (for this case it should be an input of plugin lib type), data is a reference to the message to be ingested and len the number of bytes to take from it.
Return Value
On success, it returns the number of bytes written; on error it returns -1.
Usage
For more details and an example about how to use this function properly please refer to the next section Ingest Records Manually.
Last modified 1d ago