This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
The following are the spec and example files for macros.conf.
# Copyright (C) 2005-2011 Splunk Inc. All Rights Reserved. Version 4.2.3 # # This file contains possible attribute/value pairs for search language macros. # To learn more about configuration files (including precedence) please see the documentation # located at http://www.splunk.com/base/Documentation/latest/Admin/Aboutconfigurationfiles [<STANZA_NAME>] * Each stanza represents a search macro that can be referenced in any search. * The stanza name is the name of the macro if the macro takes no arguments. Otherwise, the stanza name is the macro name appended with "(<numargs>)", where <numargs> is the number of arguments that this macro takes. * Macros can be overloaded. In other words, they can have the same name but a different number of arguments. If you have [foobar], [foobar(1)], [foobar(2)], etc., they are not the same macro. * Macros can be used in the search language by enclosing the macro name and any argument list within tick marks, for example:`foobar(arg1,arg2)` or `footer`. * Splunk does not expand macros when they are inside of quoted values, for example: "foo`bar`baz". args = <string>,<string>,... * A comma-delimited string of argument names. * Argument names can only contain alphanumeric characters, underscores '_', and hyphens '-'. * If the stanza name indicates that this macro takes no arguments, this attribute will be ignored. * This list cannot contain any repeated elements. definition = <string> * The string that the macro will expand to, with the argument substitutions made. (The exception is when iseval = true, see below.) * Arguments to be substituted must be wrapped by dollar signs ($), for example: "the last part of this string will be replaced by the value of argument foo $foo$". * Splunk replaces the $<arg>$ pattern globally in the string, even inside of quotes. validation = <string> * A validation string that is an 'eval' expression. This expression must evaluate to a boolean or a string. * Use this to verify that the macro's argument values are acceptable. * If the validation expression is boolean, validation succeeds when it returns true. If it returns false or is NULL, validation fails, and Splunk returns the error message defined by the attribute, errormsg. * If the validation expression is not boolean, Splunk expects it to return a string or NULL. If it returns NULL, validation is considered a success. Otherwise, the string returned is the error string. errormsg = <string> * The error message to be displayed if validation is a boolean expression and it does not evaluate to true. iseval = <true/false> * If true, the definition attribute is expected to be an eval expression that returns a string that represents the expansion of this macro. * Defaults to false. description = <string> * OPTIONAL. Simple english description of what the macro does.
# Copyright (C) 2005-2011 Splunk Inc. All Rights Reserved. Version 4.2.3 # # Example macros.conf # # macro foobar that takes no arguments can be invoked via `foobar` [foobar] # the defintion of a macro can invoke another macro. nesting can be indefinite and cycles will be detected and result in an error definition = `foobar(foo=defaultfoo)` # macro foobar that takes one argument, invoked via `foobar(someval)` [foobar(1)] args = foo # note this is definition will include the leading and trailing quotes, i.e. # something `foobar(someval)` # would expand to # something "foo = someval" definition = "foo = $foo$" # macro that takes two arguments # note that macro arguments can be named so this particular macro could be invoked equivalently as # `foobar(1,2)` `foobar(foo=1,bar=2)` or `foobar(bar=2,foo=1)` [foobar(2)] args = foo, bar definition = "foo = $foo$, bar = $bar$" # macro that takes one argument that does validation [foovalid(1)] args = foo definition = "foovalid = $foo$" # the validation eval function takes any even number of arguments (>=2) where the first argument is # a boolean expression, the 2nd a string, the third boolean, 4th a string, etc etc etc validation = validate(foo>15,"foo must be greater than 15",foo<=100,"foo must be <= 100") # macro showing simple boolean validation, where if foo > bar is not true, errormsg is displayed [foovalid(2)] args = foo, bar definition = "foo = $foo$ and bar = $bar$" validation = foo > bar errormsg = foo must be greater than bar # example of an eval-based definition. For example in this case `fooeval(10,20)` would get replaced by 10 + 20 [fooeval(2)] args = foo, bar definition = if (bar > 0, "$foo$ + $bar$", "$foo$ - $bar$") iseval = true
This documentation applies to the following versions of Splunk: 4.2.3