Fluent Bit: Official Manual
Search…
1.8
Installation
Administration
Data Pipeline
Stream Processing
Lua
Due to the necessity to have a flexible filtering mechanism, now is possible to extend Fluent Bit capabilities writing simple filters using Lua programming language. A Lua based filter takes two steps:
- Configure the Filter in the main configuration
- Prepare a Lua script that will be used by the Filter
Configuration Parameters
The plugin supports the following configuration parameters:
Key
Description
script
Path to the Lua script that will be used.
call
Lua function name that will be triggered to do filtering. It's assumed that the function is declared inside the Script defined above.
type_int_key
If these keys are matched, the fields are converted to integer. If more than one key, delimit by space. Note that starting from Fluent Bit v1.6 integer data types are preserved and not converted to double as in previous versions.
protected_mode
If enabled, Lua script will be executed in protected mode. It prevents to crash when invalid Lua script is executed. Default is true.
time_as_table
By default when the Lua script is invoked, the record timestamp is passed as a Floating number which might lead to loss precision when the data is converted back. If you desire timestamp precision enabling this option will pass the timestamp as a Lua table with keys
sec for seconds since epoch and nsec for nanoseconds.Getting Started
In order to test the filter, you can run the plugin from the command line or through the configuration file. The following examples uses the dummy input plugin for data ingestion, invoke Lua filter using the test.lua script and calls the cb_print() function which only print the same information to the standard output:
Command Line
From the command line you can use the following options:
1
$ fluent-bit -i dummy -F lua -p script=test.lua -p call=cb_print -m '*' -o null
Copied!
Configuration File
In your main configuration file append the following Input, Filter & Output sections:
1
[INPUT]
2
Name dummy
3
​
4
[FILTER]
5
Name lua
6
Match *
7
script test.lua
8
call cb_print
9
​
10
[OUTPUT]
11
Name null
12
Match *
Copied!
Lua Script Filter API
The life cycle of a filter have the following steps:
- Upon Tag matching by filter_lua, it may process or bypass the record.
- If filter_lua accepts the record, it will invoke the function defined in the call property which basically is the name of a function defined in the Lua script.
- Invoke Lua function passing each record in JSON format.
- Upon return, validate return value and take some action (described above)
Callback Prototype
The Lua script can have one or multiple callbacks that can be used by filter_lua, it prototype is as follows:
1
function cb_print(tag, timestamp, record)
2
return code, timestamp, record
3
end
Copied!
Function Arguments
name
description
tag
Name of the tag associated with the incoming record.
timestamp
Unix timestamp with nanoseconds associated with the incoming record. The original format is a double (seconds.nanoseconds)
record
Lua table with the record content
Return Values
Each callback must return three values:
name
data type
description
code
integer
The code return value represents the result and further action that may follows. If code equals -1, means that filter_lua must drop the record. If code equals 0 the record will not be modified, otherwise if code equals 1, means the original timestamp and record have been modified so it must be replaced by the returned values from timestamp (second return value) and record (third return value). If code equals 2, means the original timestamp is not modified and the record has been modified so it must be replaced by the returned values from record (third return value). The code 2 is supported from v1.4.3.
timestamp
double
If code equals 1, the original record timestamp will be replaced with this new value.
record
table
if code equals 1, the original record information will be replaced with this new value. Note that the format of this value must be a valid Lua table.
Code Examples
For functional examples of this interface, please refer to the code samples provided in the source code of the project located here:
Number Type
In Lua, Fluent Bit treats number as double. It means an integer field (e.g. IDs, log levels) will be converted double. To avoid type conversion, Type_int_key property is available.
Protected Mode
Fluent Bit supports protected mode to prevent crash when executes invalid Lua script. See also Error Handling in Application Code.
Last modified 7mo ago