Parser Extensions

A parser extension is a small VRL overlay attached to a single log source. It runs as an extra Vector transform chained between the OOTB parser's parse step and its output step. Use it to add a field, normalize a value, or drop a noisy event for one tenant or one feed — without forking the OOTB parser and losing upgrades.

What an Extension Is

An extension is a VRL transform that runs after the OOTB parser has already produced the canonical UDM shape (.udm.*, .metadata.*, .ext, .message, .source_type) and before the output flatten step that prepares the event for ClickHouse.

Because the extension sits between _parse and _output, it sees the same .udm.* shape the parser produced — you can set, override, or delete UDM fields directly, and the flatten step still runs uniformly afterward.

Common Use Cases

What Extensions Are Not For

• Replacing the OOTB parser. If the base parser is structurally wrong for your logs (different format, different vendor variant), generate a new parser from samples instead — that's still the right tool for the job.
• Cross-source logic. Extensions are per-log-source. Logic that spans sources belongs in detection rules or enrichment.
• Stateful processing. Extensions are stateless transforms — no aggregation, no joins, no lookups against other events.

The Stub Case (No OOTB Parser)

If the log source's parser_vrl is empty and the extension is enabled, the extension is the parser for that source type. The pipeline skips the _parse stage entirely and the extension consumes from the router directly:

The Extension tab makes this explicit — when no OOTB parser exists for the source type, the read-only base pane shows a "your extension will be the parser" hint and you author the full transform there.

Authoring an Extension

Walkthrough

1. Open the log source at Feeds → select source → log-source detail page
2. Click the Extension tab (between VRL editor and Deployments)
3. Write the overlay. The top pane shows the OOTB parser read-only; the bottom pane is your editable VRL. The AI sidebar accepts natural-language edits — it's pinned to "only emit the extension, don't touch the base parser"
4. Test with a sample event. The Test button runs parser_vrl → extension_vrl against your sample and shows the final event shape — exactly what would land in ClickHouse
5. Enable the toggle, Save the draft, then Publish + Deploy from the page header to push to Vector

Worked Example: Tag CloudTrail with a Team

You manage two AWS accounts — production and analytics — and want every CloudTrail event tagged with the responsible team so dashboards and detections can filter cleanly.

1. Open the aws_cloudtrail_prod log source → Extension tab

2. Write:

   if .udm.cloud_account_id == "111111111111" {
       .udm.team = "platform"
   } else if .udm.cloud_account_id == "222222222222" {
       .udm.team = "data"
   }

3. Paste a sample CloudTrail event into the Test panel and click Test — confirm team appears in the output

4. Toggle Enabled → Save → Publish from the page header

The OOTB CloudTrail parser keeps running unchanged. Your team tag rides on top.

Worked Example: Drop a Noisy Health Check

A firewall feed includes health-check pings that double your event volume but never trigger detections:

if .udm.action == "allow" && .src_ip == "10.0.0.5" && .dest_port == 443 {
    abort
}

abort in VRL halts the transform and drops the event before it reaches the combiner. The OOTB parser still processes everything else.

Validation — Three Gates

Invalid extension VRL never reaches a running Vector. nano enforces three independent layers:

The AI sidebar re-validates every suggestion before returning it, so accepted suggestions are almost always already publish-clean. Save persists your draft as-is; the validation gates fire when you publish.

Version History

Extensions piggyback on the same publish/version flow as the base parser:

• Each Publish snapshots both parser_vrl and extension_vrl into a new version
• The Versions tab diff shows changes to either
• Revert restores both fields to the chosen version's snapshot — you don't have to revert parser and extension separately

Sampling Interaction

Extensions run before the optional sample transform, so an enabled extension applies to every event before sampling decisions. A normalization or enrichment in the extension is visible to the sampling exclude condition, which means you can write rules like:

.udm.criticality = if .src_ip == "10.0.1.5" { "high" } else { "low" }

and then exclude criticality == "high" from sampling on the Configuration tab.

Limitations (v1)

• One extension per log source. Stacking multiple extensions with explicit ordering will come later — for now, compose your logic in a single transform.
• VRL only. No declarative shorthand for common cases like "add a constant field." Use VRL with one-line assignments.
• No conflict lint. If you set .udm.user in your extension and a future OOTB parser update also sets it, the extension wins (it runs second). Watch the Versions diff when pulling parser updates.
• No cross-source library. Each log source's extension is its own artifact; copy-paste between sources for now.

Related

• Data Ingestion — feed onboarding, AI parser generation, publish flow
• Supported Data Sources — which sources support source_type natively
• UDM Fields — canonical field names available in extensions