Splunk Basic : Everything to know about macros

Okay. Today, we'll discuss Splunk

macros. Okay. So, Splunk macros--you can

think of them as reusable components in

your Splunk search where, suppose a

particular search portion is

if you used many times, then you

can put it in a macro so that you can

call that macro, and the macro will be

replaced at runtime with that search string.

Okay? So, macros are very, very useful when,

suppose you have many dashboards in your

application. And in all these dashboards, you

have some search which is running in all

the dashboards. Right? So, in this case, you

can implement that search portion in a

macro so that you can just call that macro

instead of using the whole search string in

your dashboards. So, in the future, if you

want to make any changes in that search

logic, we'll just change it in

one place--in that macro body. Okay?

So, by implementing a macro, basically, we

are achieving two things. One is the

modularity of your code--easy

maintenance of your code--as well as

your search string will be much

smaller. Okay? So, there are

two different types of macros we

generally deal with. One is an eval-based

macro, and another is a non-eval-based

macro. So, before we discuss those things,

let me show you the data I have here.

So, I have some people's names, their

basic salary, and variable percent. So,

I'll show you how to create an eval-based macro,

how to create a non-eval-based

macro, what the differences are

between them, and then how to call a

macro instead of the macro also. We'll try to

discuss that one. Because first, let us

see how we can create a non-eval macro.

So now, an eval macro and a non-eval macro--

if you see functionality-wise, both are the

same. So, when we define a macro--the macro

body--you are giving the search string. Right? So,

dynamically at runtime, that

macro will be replaced

by that macro body by Splunk search.

Okay? Now, when we talk about eval-based

macros, it is expected that the macro is

returning a string. When you use a non-eval-based macro,

you can directly put the

search string inside the macro. So, let me

show you. Suppose I want to calculate

total salary based on this formula:

called basic salary. Let me show you.

Basic salary plus basic into the

percentage--variable

percent. Okay? So, to do that--to create any

macro from the Splunk UI--this is how you

do it. You'll go to Settings. We go to

Advanced Search. Okay? From there, if you

see, there is an option called Search Macros.

You go there. You select your app

from there. So, I'll be creating this

macro in my TMDB app. So, I have selected

TMDB over here, then New Search Macro.

Okay? If you see the destination, I've

already selected it as TMDB. I'll give it a

name. Let's say, total salary. Okay? So now,

whether a macro is eval-based or not is

determined by this checkbox. If you

check this one, it will be an eval-based

macro. If you don't check this one,

it will be a non-eval-based macro. So

first, we'll discuss the non-eval-based macro.

So, what I am trying to say

is--whenever we

are creating a non-eval-based macro, we

can directly give a search string over

there. So, my search string will be

something like this. I'll be creating a

new field called total salary. So, that's

why eval total_salary =. Now,

I'll be passing this to my basic

salary and variable percent to this

macro. Right? To do that, what I'll do

is create arguments for this macro:

basic salary. So, in the argument

section, you'll be giving

these two things: basic salary and

variable percent. That's two arguments. As the

macro has two arguments, it is mandatory

that in this Name section, you give how

many number of arguments you have in

your macro. If it is one, you have to give

one here. Okay? Now the formula is: my

basic salary. Now, this basic salary is my

input variable. Right? So, to access input

variables, you access like this--just like

a token. Okay? Basic salary plus my basic

salary into that variable percent. Again,

as input, I am accessing. Right? Then

divided by 100. So, this will be my

macro body. Now, there are two options

for Validation Expression and Validation

Error Message. I will show you in the

next macro. So, if I save it--okay.

So, if you see, the macro has been created.

Now, if I call this macro over here--so to

call a macro, this is how you call: there

is a tick mark, if you see, okay, from your

keyboard, then the macro name--total

salary--and it has two arguments, right? My

basic salary and my variable percent,

then tick end. Now, this basic salary

corresponds to this basic salary, and

variable percent corresponds to this

variable percent field.

Now, when you define the macro, I have

given the same name as the macro input. You

can give any input variable name

over here. The same name you have to use

over here as well. But when you pass the

macro--pass this with basic salary and variable

percent to this macro--you'll be giving

the field names only. Okay?

So, let us run it and see what's going on.

If you see, it has created a total salary

field with this formula output--4,000 plus

4,000 into 15% is 4,600. Right? So, it is

basically the same as what is

happening at runtime. So, if

instead of total salary, I just gave

this one, and instead of this token

variable, I just gave my field name here,

the output will be the same--variable percent.

The output will be the same. So, this is also

what is happening as well. So, at runtime,

Splunk is replacing this macro body with

these variable inputs, and then it is

running the query. So ultimately, this

query is getting run. Okay? But the

thing is--this code, if you put it in

a macro--you can call that macro anywhere

in usage. So that means this code

portion will be reusable now. Okay? Now,

let's see an example where we can use

this validation expression and

validation error message. Now,

validation expression is used when you

want to do some kind of validation on

your macro inputs. Okay? And validation

error message means when this input is

getting--or this validation is getting--

failed, this error message will be

displayed over there. So, to do that, what

I'll do is create another macro.

Okay? So now, let's say, we have basic

salary and variable percent. Right? Let's

say we want to calculate a bonus

percentage with this formula: called

variable percent plus any other percent--

any number. Let's say, any number--

7% or 8%, any number

I’ll put for our inputs. It'll give me--it'll

add those two percentage values and

give me the bonus percent. Okay? So, to do

that, I'll just create that similar

macro named "bonus."

Okay? So, the formula will be--again--it

will be non-eval-based. Okay? eval bonus =.

So, my variable percent, right,

I have to provide as an input, so I'll be

giving input. So, let's say this time I

will rename this to something--VP. So,

I'll say $VP$, then plus

another input I'll be giving--let's say,

bonus input. Okay? So, this bonus, I'll be

adding here. Okay. Bonus. So, we have two

inputs. That means we have to give two

over here. Now I'll add an expression. Now,

I always want this bonus to be a number.

Okay? To do that--so, this validation

expression has to be a Boolean

expression or eval. Okay? So, if you saw my

previous video, we discussed the

various eval expressions. Right? And some

of the expressions return Boolean--like

the like operator, in operator, or

isnum operator, which basically checks

whether a particular input is a number or

not. So, we'll be using isnum over

here on this bonus. That means I am

checking whether whatever I am providing

as input to this bonus variable

parameter is a number or not. If

it is not a number, I'll give this

output error message: "Bonus must

be a number." Okay?

So, let's save this macro. Okay? Now I will

call this macro here. Let it be--my total

salary macro called as--is. If I just do

Ctrl+C--

okay. Here, I am calling my total salary. So

just tick the output. Now, after that, I'll

be calling the bonus macro. Right? So,

similar way: tick, macro name, macro

inputs. One of the inputs will be my

variable percent, and another

input maybe--let's say, 8% I want

to add to the variable percent. So, what

will be the output? In this case, it should

create a new field called "bonus" with 15

plus 8, 20 plus 8—something like this.

Okay? If you see, you can

access different macros in

your whole search. Okay? Now, let's say I

have provided a string here--it says test.

Okay. What is happening? So, if you provide

a string here, that validation is

getting failed. We have added over here

isnum. So, that's why it is giving you this

error: "Bonus must be a number." So, this is

how macro input validation works. Okay. Let

us continue. Now, we will discuss

how to create an eval macro. So, to do

that, what we'll do is--first, let me show

you two things. If you remember from my

previous video, we created a command

called getjournals. Right? And that

command takes an input with the journal

ID. And if we are not giving any journal

ID and we are giving *, it will give you all

the journal details. Right? And also, we

have... We have created a...

We have indexed our data into this main index.

Right? So, we have another dataset

called "main" where we are having

this salary and this information. Just

now we are working with this dataset. So,

suppose there is a requirement that,

based on a certain condition, either I need

to go with this dataset or I need to go

with that dataset. In this type of

scenario--where dynamically you have to

determine which dataset to work on, or

dynamically determine

which search string to return--

eval macros

come into the picture. Okay? Because the

main concept behind an eval macro is it has

to return a string. So, in that case, how

you will create it is like this. Let's say,

new search macro. I'll give a name called

getjournal_or_mainindex. Okay? Just

like a name to show you the use

case of it. So, here, what I will write--

I’ll write an if or case statement. Generally,

we mostly write an if or case

statement for eval-based macros,

so that we can have different

conditions, and based on the condition, we

return the search string. But

ultimately, if you see, we’re returning the

search string only at the end of the day--

so that Splunk will replace that macro

with that search string. So, I’m saying I’ll

provide the argument here. Let’s say,

same argument name. So,

either I’ll provide getjournal, or I’ll

provide main as my argument

value. Okay? I’ll show you how I

provide that one.

case($input$ == "getjournal", "getjournals *", $input$ == "main", "search index=main")

As it is within quotes, remember that this one

has to be in quotes as well. Or, when you are

calling it, you have to call with

quotes. I prefer it like this only so

that everything is inside your

macro. In that case, the string I

will return is this command: getjournals *.

Now, you have to be very careful over

here when you deal with a generating

command. If you see, getjournals is a

generating command. Right? That’s why this

has to be the first command in your

search string. Now, for generating commands,

when you run it--if you see--there is a

bar (|) over here in the search bar. Right? After

that only, if I run this command without

this bar, nothing will come up. So,

it requires this bar. But when you put

this getjournals *--this generating

command--inside a macro, you put it

without the bar, so that when you call

the macro, you’ll call with | then

macro name. I’ll show you that one as

well. That’s why I’m giving it without

the bar here. This is important--you have to be very

careful with generating commands.

Because if you put the bar inside, it will

not work. Now, when my input is "main"--okay--in

that case, I will return the string

called search index=main. Here

also, another good thing is when you run

index=main from your search

prompt, you do not need to mention

search then index=main,

because that comes by default. But

when you use it in a macro or somewhere

else,

you have to put it like this: search

index=main. Okay? So, this string I’ll

be returning. Since the macro has one

input, I’ll be giving 1 here. Okay? For now,

validation. We are not doing anything,

so let’s save it. Okay? This is our third

macro--getjournal_or_main. So, if I

run this macro now--okay--as I said, it

has a generating command, that’s why I’m

giving a bar over here, then my tick, and

then my input. Let’s say I’ll be giving

input as getjournal. I

want to work with the dataset getjournal. Okay?

Let’s see. Okay. I have a

bracket that’s missing over here. Save.

If you see, if I run this macro again, it

is giving me the same because sometimes it

doesn’t take the refreshed value.

So, what I’ll do in this case--just copy

this code, close it, run it again.

SearchFactory Unknown search command

'case'. Let’s see what’s going on. Okay. It

has to be an eval-based macro because it is

returning a string now. Right? So, let’s

save it, and let’s rerun it. Okay. It is not-- Okay. Now, if you

see, if I run this getjournal macro,

it is giving me this dataset where it

is running that getjournal *

generating command and giving me this

result. If I say main, in this case, it is

giving me this dataset where I have

indexed my data. So, this is how you can

create an eval-based macro. Okay? So now,

macros have different permissions as

well. If you see from this macro

list page, you can set the

permissions as well. So currently, I'll

show you. I'll set this permission as

"this app only" and read--I'll say

everyone, and write--let's say, admin. Let's

do it for all the macro permissions. So,

you have to be very careful with the

macro permissions as well. Otherwise, any

unprivileged user will not be able to

run this macro, and your dashboard will

not show up anything. So, read--right. Okay.

Now, we have set the permissions of the

macro as well. Now, let's see what's going

on in the background. So, I am in my

Splunk home. I'll go to etc/apps/tmdb_app/,

and I'll go to my local folder. If

you see, whenever you create a macro,

it creates another conf file called

macros.conf. I'll open this file. And

if you see all the different macros we have

created, it creates separate

stanzas for each macro name with all

the input numbers. Right? And args are the

inputs of these macros. Right? For bonus, if

you see here, my arguments are

VP and bonus. Right? Two arguments--those are

showing up here. This is

the macro definition. This is the error

message you set for this macro. This

is the validation you have set for

this macro. And iseval is telling

you whether this macro is eval-based or

not. As our last macro, getjournal_or_main,

is eval-based, that's why iseval is

1. For the rest of the two macros, iseval

is 0. Okay? Now, you can call a

macro inside another macro. So, to

do that, let's do this exercise where we

have created this totalsalary, right?

And also bonus.

So, inside totalsalary, we'll try to

call this bonus one. To do that, I'll

do one thing. I'll clone this totalsalary macro.

No--let's just

get a new one only. Let's say, totalsalary_v2 (version two).

Okay? So, what I will do--it will

not be an eval-based macro. Let's say my

previous one was eval, right? So,

it has two arguments: basic_salary and

variable_percent. Right? Now, I'll be

adding this bonus as well. So, bonus

requires another extra input called

bonus, right? So, I'll be adding this as

an extra input--comma, this. So, my total

macro inputs will be three. basic_salary

and variable_percent will be used

here, and variable_percent and bonus will be

used in another eval statement,

which you'll be calling in this

bonus macro. Right? So, in this case, I'll

be calling this bonus macro inside. So,

I'll set this one—pipe, then my bonus

macro. bonus macro takes two arguments.

One is variable_percent, and another is

bonus. So, variable_percent I'll pass, and

I'll pass this bonus as well. So, ideally,

the behavior should be the same as we have

seen before. Right? So,

done. Tick. Okay. Now, let's save it. Okay.

So, totalsalary_v2. So, before we do

that, let us run our macro. So, I'll

just copy-paste that code portion here.

Right. So, I'll just copy-paste this code

portion here.

It's mac_totalsalary_non--okay, I

think my macro is totalsalary. It

It has mismatched parenthesis. Okay. Okay. So,

it has created this one. In this new

field, in the new search field, what I'll

do is--after this one--

I'll be calling my totalsalary_v2 macro.

Okay? Where it is doing

the work of both of these two--bonus and

totalsalary. Right? So, totalsalary_v2.

Okay. So, my tick--v2. v2

requires three arguments. One

is my basic_salary, variable_percent, and

the similar percent value--I'll give 8

so that we can at least compare

the outputs. So, if I run this one--see--

it is working in the same way,

where it is getting this bonus field and

totalsalary. And if you see, the output

is same as well.

$15.22. We have given 7 here. Okay.

Let's run it with 7 only. So,

if you see--15.22, 20.22, 17.10, 17 like this.

Okay? So, this is how you can call a macro

inside another macro as well. So, if you

see here, by this structure, you

can achieve a very complex structure as

well--a complex structure which

is basically a reusable component in

Splunk search queries. Okay? So, this is what

you need to know, basically, to deal with

macros. And macros are very useful in

Splunk because not only do they give

you the modularity approach, but also

they give you a very short

search string and very readable code as well.

Okay? See you in the next video.