Blog

Introducing Gravwell Macros

Nov 27, 2019 9:24:55 AM / by John Floren

One of the exciting new features in Gravwell 3.3.0 is search macros. Anyone who's experimented much with Gravwell knows you may often end up crafting a long and complex regular expression which you'll want to use over and over, but such a long regex makes the query hard to work with. Macros let you turn that long regular expression (or any other part of a search query) into a much shorter name you can use again and again.

Macros are defined and managed in a new interface, located in the 'Library' section of the main menu:

menu

Macro Basics

Macros are essentially string replacement rules. You define a macro that maps a short, all-caps name to a longer string. When parsing a search query, Gravwell looks for macro names preceded by a dollar sign and does the replacement before launching the search. We might have a particular regular expression we use to extract DHCP information from system logs. We'd like to make a macro so we don't have to type out the whole regex each time, so we define a macro as follows:

dhcpack

This tells Gravwell that when it sees $DHCPACK in the query, it should replace it with regex "DHCPACK on (?P<ip>\S+) to (?P<mac>\S+) via (?P<iface>\S+)". Now we can just use the macro in queries whenever we wish:

tag=syslog $DHCPACK | unique ip mac | table ip mac

Note that a macro can contain search modules, tag specifications, pipes, or render modules; behind the scenes, Gravwell is just doing string replacement. If you have a query you intend to run often, you can simply put the entire query into a macro named MYMACRO; typing $MYMACRO in the search box and hitting enter will run the full query for you.

When you type a macro in the query bar, Gravwell will show the actual expansion below for convenience:

expansion

 

Macro Arguments

Gravwell macros, like C macros, can take arguments. Suppose you have Bro/Zeek HTTP logs ingested under the 'bro-http' tag and you'd like to be able to rapidly pull out only those logs with a particular user agent. We can do that with a macro that contains an argument:

httpuser

The query string, `tag=bro-http ax user_agent~"%%1%%"` contains a special form, %%1%%, which will be replaced by the first argument to the macro. Entering `$HTTPUSER(curl)` will expand to `tag=bro-http ax user_agent~curl`, which show us entries whose user_agent field contains the string "curl":

httpresults

If you want more arguments, just use %%2%%, %%3%%, etc. There's no limit, and you can use any given argument multiple times in the expansion.

Nested Macros

A macro can contain other macros. The screenshot below shows a macro named $FOO whose expansion contains another macro, $BAR. When you type $FOO into the search bar, it first expands $FOO, then seeing that the query still contains a macro ($BAR), it expands again.

foo

 

bar

 

foo-expand

Macros can also take macros as arguments. The following macro defines a simple filter on the source IP of packets:

src

We have another macro which defines the IP address of the local network's router:

router

We can then use $ROUTER as an argument to $SRC:

src-expand

 

Conclusion

Gravwell macros are pretty flexible; you can use them to simply reduce typing, or you can get tricky with nested macros. If you'd like some help coming up with good reusable macros for your Gravwell install, drop us a line at info@gravwell.io. If you're new to Gravwell but want to see what it's all about, you can sign up for our free Community Edition below!

Get Community Edition

 

Topics: Software Updates

John Floren

Written by John Floren

John's been writing Go since before it was cool and developing distributed systems for almost as long.