LUA Transform

The Vector lua transform accepts and outputs log events allowing you to transform events with a full embedded Lua engine.

Configuration

vector.toml

[transforms.my_transform_id]
  # REQUIRED
  type = "lua" # must be: "lua"
  inputs = ["my-source-id"] # example
  source = """
require("script") # a `script.lua` file must be in your [`search_dirs`](#search_dirs)

if event["host"] == nil then
  local f = io.popen ("/bin/hostname")
  local hostname = f:read("*a") or ""
  f:close()
  hostname = string.gsub(hostname, "\n$", "")
  event["host"] = hostname
end
"""

  # OPTIONAL
  search_dirs = ["/etc/vector/lua"] # example, no default

Options

2 items

common onlyrequired only

[string]commonoptional

search_dirs

A list of directories search when loading a Lua file via the require function. See Search Directories for more info.

No default

View examples

stringcommonrequired

source

The inline Lua source to evaluate. See Global Variables for more info.

No default

View examples

Output

• Add Fields
• Remove Fields
• Drop Event

How It Works

Dropping Events

To drop events, simply set the event variable to nil. For example:

if event["message"].match(str, "debug") then
  event = nil
end

Environment Variables

Environment variables are supported through all of Vector's configuration. Simply add ${MY_ENV_VAR} in your Vector configuration file and the variable will be replaced before being evaluated.

You can learn more in the Environment Variables section.

Global Variables

When evaluating the provided source, Vector will provide a single global variable representing the event:

Name	Type	Description
event	table	The current [log event]. Depending on prior processing the structure of your event will vary. Generally though, it will follow the default event schema.

Note, a Lua table is an associative array. You can read more about Lua types in the Lua docs.

Iterate over fields

To iterate over all fields of an event use the pairs method. For example:

# Remove all fields where the value is "-"
for f,v in pairs(event) do
  if v == "-" then
    event[f] = nil
  end
end

Lua Manual

Understanding Lua and how write it is outside of the scope of Vector. We encourage you to take a look at the Lua manual for more information.

Lua Version

Vector uses the rlua Rust crate which currently embeds Lua 5.3.

Nested Fields

As described in the Data Model document, Vector flatten events, representing nested field with a . delimiter. Therefore, adding, accessing, or removing nested fields is as simple as added a . in your key name:

# Add nested field
event["parent.child"] = "nested value"

# Remove nested field
event["parent.child"] = nil

Search Directories

Vector provides a search_dirs option that allows you to specify absolute paths that will searched when using the Lua require function.