liveBook · Manning

Lua

As explained in Logs and Telemetry

Lua is a lightweight embeddable scripting language commonly used to add programmable behavior to host applications.

Lua is a lightweight scripting language for embedding custom behavior in event-processing systems. It suits small, context-specific transformations that configuration-only filters cannot express, while keeping that logic separate from the core implementation. section 1.3.3 section 7.6.1

In Fluent Bit, a Lua filter receives an event tag, timestamp, and record, then returns a numeric status with the timestamp and record. Records arrive as Lua tables: name-value structures that can contain nested tables, so scripts can iterate through or recursively transform event content. The tag cannot be returned or changed by the script. section 7.6.2

Use a Lua filter when custom processing needs to:

  • Combine work otherwise spread across multiple filters or parsers, where a single script may be more efficient. section 7.6
  • Perform computations unavailable in existing filters, including date-format conversion, time-zone handling, and daylight-saving adjustments. section 7.6
  • Mask sensitive values in uncommon data formats that lack a predefined utility. section 7.6
  • Extend processing around logs, traces, and metrics before considering a custom plugin. section 9.0

Lua can run interpreted or through LuaJIT; Fluent Bit uses the JIT compiler for Lua scripts. A well-written script can perform well, but JIT compilation adds overhead and does not match already native-compiled code. Prefer Lua for logic that belongs with pipeline configuration rather than the core codebase. section 7.6.1

Count and annotate event fields

A recursive script traverses a log record, counts root and nested elements, prints field names, adds an element_count field, and changes remote_user when present. Configure the Lua filter with the script path and callback name; Fluent Bit invokes that function for matching events. section 7.6.2

Table 7.1 Response-code values and their meanings
Code
Meaning
–1
The record needs deleting.
  0
All values are unmodified.
  1
Both timestamp and record structures have changed, and the Fluent Bit record needs to be updated.
  2
Only the record has changed, and the timestamp remains unmodified.

Choose the callback response code that matches whether the script deletes an event, leaves it unchanged, changes its record, or changes both record and timestamp. section 7.6.2

How Logs and Telemetry covers it

How deep it goes
Explains callback inputs, Lua tables, recursive traversal, return codes, and filter configuration; defers broader extension trade-offs.
Examples
Demonstrates an attribute-counting script that recursively inspects records, changes remote_user, and configures dummy inputs.
What it assumes
Assumes familiarity with Fluent Bit event processing while introducing Lua callback arguments and table-based records.
What you can do after
Apply it via Fluent Bit’s Lua filter to inspect, annotate, transform, or delete event records.
How it connects
Connects Lua to Fluent Bit filters, parsers, processors, custom plugins, LuaJIT, and data masking.
Cover of Logs and Telemetry
liveBookmanning.com
Read Logs and Telemetry on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Logs and Telemetry. The section links point to the parts of the book it draws on.