What Is Custom Fields By Lua? Definition & Examples

A log configuration pattern that lets teams set or replace fields with Lua code at emit time. Each key maps to a code block whose return value becomes the log field value. It is commonly used to reshape gateway telemetry into a schema that external tools can ingest cleanly.

What Custom Fields By Lua Does

Custom Fields By Lua is a log formatting pattern that evaluates Lua expressions at emit time, so each field can be computed, transformed, or replaced before the event leaves the system. It is most useful when downstream tooling expects a clean, stable schema but the source telemetry is inconsistent or overly verbose.

The key idea is that the log pipeline does not just copy static fields. Instead, it executes a small Lua block for each configured key, and the returned value becomes the field value in the emitted record. That makes the pattern powerful for normalization, enrichment, redaction, and conditional shaping without changing the source application.

How Emit-Time Field Shaping Works

At emit time, the logging pipeline evaluates the Lua code in the context of the current event. The code can inspect existing fields, derive new values, or suppress unwanted detail by returning a replacement value. This is different from post-processing after the log has already been written, because the output record is finalized before ingestion.

Because the transformation happens while the event is being emitted, the pattern can enforce a consistent schema at the edge of the pipeline. That is especially useful when logs from multiple services, plugins, or tenants need to be merged into a common format for search, alerting, or analytics.

Why Teams Use It for Telemetry Normalization

Operators use this pattern when raw logs do not match the shape required by SIEM, observability, or compliance tooling. Lua makes it possible to map provider-specific fields into canonical names, compute labels from multiple inputs, or remove noise that would otherwise fragment queries and dashboards.

It also supports targeted enrichment, such as deriving environment, tenant, route, or severity fields from request context. Used carefully, that reduces schema drift and makes downstream correlation much easier. Used carelessly, it can also hide source detail or create inconsistent field semantics if different Lua blocks implement different rules for the same key.

Security and Operational Implications

Custom field logic is part of the trust boundary of the logging pipeline because it can change what evidence is preserved, exposed, or forwarded. Field rewriting can improve privacy by removing sensitive values, but it can also weaken investigations if the transformation strips context needed for incident response.

The main operational concern is consistency. If field logic is spread across many configurations, teams can end up with silent differences in log meaning, especially when the same source event is shaped in more than one place. That is a schema-governance problem as much as a formatting one, because downstream detections and reports depend on the stability of those fields.

Common Uses and Failure Modes

Common uses include renaming vendor-specific attributes, generating derived tags, masking sensitive values, and converting free-form text into structured output. These are valid when the resulting field has a clear meaning and is predictable enough for downstream consumers to rely on.

Failure modes usually show up as malformed output, inconsistent return values, expensive code in the hot path, or logic that diverges across environments. A field rule that behaves differently in staging and production can create analysis gaps that are hard to spot because the logs still look syntactically valid.

Risk and Threat Considerations

Custom field code sits close to the telemetry source, so mistakes can alter what evidence is available for detection, forensics, and compliance review. If Lua logic rewrites or drops important fields, an organisation may lose visibility into attacks, outages, or policy violations even though the pipeline appears healthy.

Failure mechanism: A transformation bug, overly aggressive redaction rule, or inconsistent field mapping changes the meaning of emitted logs, removes key context, or creates misleading records that downstream tools trust as authoritative.

Impact: Security monitoring, incident triage, and audit workflows can miss real events, misclassify activity, or rely on incomplete telemetry, which increases dwell time and weakens investigations.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

NIST SP 800-53 Rev 5 provides the primary governance reference for this term.

Framework	Control / Reference	Relevance
NIST SP 800-53 Rev 5	AU-2 — Event Logging	Custom field shaping changes what audit events retain for monitoring and investigation.
	AU-3 — Content of Audit Records	Lua field mapping directly determines the content and structure of audit records.
	AU-6 — Audit Record Review, Analysis, and Reporting	Reliable field normalization is needed for downstream review and correlation of logs.
Recommendation — Define required log fields and preserve investigation-relevant context in emitted records. Standardize audit record content so emit-time transforms keep required details consistent. Validate transformed fields so audit review and correlation remain dependable.

Practitioner Guidance

Governance implication: Treat custom Lua field logic as part of the logging control plane, not as a cosmetic formatting layer. The person designing the transformation should be able to explain the source field, the intended output, and the operational reason the rewrite exists.

What to watch for: Be especially cautious when the same log source is shaped in multiple places or when logic depends on environment-specific assumptions. Small differences in return values can produce large downstream differences in search, alerting, and retention behavior.

Custom Fields By Lua