Use the eval command and functions

The eval command enables you to devise arbitrary expressions that use automatically extracted fields to create a new field that takes the value that is the result of the expression's evaluation. The eval command is versatile and useful. Although some eval expressions seem relatively simple, they often can be quite complex.

This topic discusses how to use the eval command and the evaluation functions.

Types of eval expressions

An eval expression is a combination of literals, fields, operators, and functions that represent the value of your destination field. The expression can involve a mathematical operation, a string concatenation, a comparison expression, a boolean expression, or a call to one of the eval functions. eval expressions require that the field's values are valid for the type of operation.

For example, with the exception of addition, arithmetic operations may not produce valid results if the values are not numerical. For addition, eval can concatenate the two operands if they are both strings. When concatenating values with a period ( . ), the eval command treats both values as strings, regardless of their actual type.

You can think of an eval expression as everything that follows the eval command, typically to the next pipe. For example, this is an eval expression:

... | eval location=city.", ".state

However, the eval expression in this search is (eval(status=404)), which is followed by an AS clause:

sourcetype=access_* | stats count(eval(status=404)) AS status_count

Example 1: Use an eval expression with a stats function

This example searches the status field which contains HTTP status codes like 200 an 404.

If you run this search, it returns a total count of all events with a value in the status field.

sourcetype=access_* | stats count(status)

This results look something like this:

count(status)
39532

You can add a BY clause to organize the count by HTTP code.

sourcetype=access_* | stats count(status) by status

This results look something like this:

status	count(status)
200	34282
400	701
403	228
404	690
406	710
408	756
500	733
503	952
505	480

However if you want the results for only one specific status, you can use an <eval-expression>. Because the <eval-expression> returns an evaluated field, you must use the AS keyword to specify a name for the evaluated field.

This search retrieves all of the events where the sourcetype is any Apache web access log and counts the number of events where the status field value is 404. The results are placed into a field called status_count.

sourcetype=access_* | stats count(eval(status=404)) AS status_count

The results look something like this:

status_count
690

You can organize the results using a BY clause.

sourcetype=access_* | stats count(eval(status="404")) AS status_count BY source

The results look something like this:

source	status_count
tutorialdata.zip:./www1/access.log	244
tutorialdata.zip:./www2/access.log	209
tutorialdata.zip:./www3/access.log	237

Example 2: Define a field that is the sum of the areas of two circles

Use the eval command to define a field that is the sum of the areas of two circles, A and B.

... | eval sum_of_areas = pi() * pow(radius_a, 2) + pi() * pow(radius_b, 2)

The area of circle is πr^2, where r is the radius. For circles A and B, the radii are radius_a and radius_b, respectively. This eval expression uses the pi and pow functions to calculate the area of each circle and then adds them together, and saves the result in a field named, sum_of_areas.

Example 3: Define a location field using the city and state fields

Use the eval command to define a location field using the city and state fields. For example, if the city=Philadelphia and state=PA, location="Philadelphia, PA".

... | eval location=city.", ".state

This eval expression is a simple string concatenation.

Example 4: Use eval functions to classify where an email came from

This example uses sample email data. You should be able to run this search on any email data by replacing the sourcetype=cisco:esa with the sourcetype value and the mailfrom field with email address field name in your data. For example, the email might be To, From, or Cc).

This example classifies where an email came from based on the email address domain. The .com, .net, and .org addresses are considered local, while anything else is considered abroad. There are many domain names. Of course, domains that are not .com, .net, or .org are not necessarily from abroad. This is just an example.

The eval command in this search contains multiple expressions, separated by commas.

sourcetype="cisco:esa" mailfrom=*| eval accountname=split(mailfrom,"@"), from_domain=mvindex(accountname,-1), location=if(match(from_domain, "[^\n\r\s]+\.(com|net|org)"), "local", "abroad") | stats count BY location

The first half of this search is similar to previous example. The split() function is used to break up the email address in the mailfrom field. The mvindex function defines the from_domain as the portion of the mailfrom field after the @ symbol.

Then, the if() and match() functions are used.

• If the from_domain value ends with a .com, .net., or .org, the location field is assigned the value local.
• If from_domain does not match, location is assigned the value abroad.

The eval results are then piped into the stats command to count the number of results for each location value.

The results appear on the Statistics tab and look something like this:

location	count
abroad	3543
local	14136

Note: This example merely illustrates using the match() function. If you want to classify your events and quickly search for those events, the better approach is to use event types. Read more about event types in the Knowledge manager manual.

Defining calculated fields

If you find that you use a particular eval expression on a regular basis, consider defining the field as a calculated field. Doing this means that when you're writing a search, you can omit the eval expression and refer to the field like you do any other extracted field. When you run the search, the fields will be extracted at search time and will be added to the events that include the fields in the eval expressions.

Read more about how to configure this in Define calculated fields in the Knowledge Manager Manual.