Splunk® Enterprise

Search Reference

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

eval

Description

The eval command evaluates an expression and puts the resulting value into a destination field. If this destination field matches a field name that already exists, it overwrites the existing field with the results of the eval expression. The eval command evaluates mathematical, string, and boolean expressions.

Difference between eval and stats commands

The eval command creates new fields in your events by using existing fields and an arbitrary expression. The stats command calculates statistics based on fields in your events.

An image that shows two tables and an example of the eval command in between the tables. The first table shows 4 columns: A, B, C, D. The example eval command is ... eval E = ... The second table shows 5 columns. The E column is added to the right side of the table. This shows that the eval command adds columns to your output. In this example the E column is added.

Syntax

eval <field>=<expression>

Required arguments

field
Syntax: <string>
Description: A destination field name for the resulting calculated value. If the field name already exists in your events, eval overwrites the value.
expression
Syntax: <string>
Description: A combination of values, variables, operators, and functions that will be executed to determine the value to place in your destination field.

The syntax of the eval expression is checked before running the search, and an exception will be thrown for an invalid expression.

  • The result of an eval statement is not allowed to be boolean. If Splunk cannot evaluate the expression successfully at search-time for a given event, eval erases the resulting field.
  • If the expression references a field name that contains non-alphanumeric characters, it needs to be surrounded by single quotes; for example, new=count+'server-1'.
  • If the expression references literal strings that contains non-alphanumeric characters, it needs to be surrounded by double quotes; for example, new="server-"+host.

Operators

The following table lists the basic operations you can perform with the eval command. For these evaluations to work, the values need to be valid for the type of operation. For example, with the exception of addition, arithmetic operations might not produce valid results if the values are not numerical. When concatenating values, Splunk Enterprise reads the values as strings, regardless of the value.

Type Operators
Arithmetic + - * / %
Concatenation .
Boolean AND OR NOT XOR < > <= >= != = == LIKE

Operators that produce numbers

  • The plus ( + ) operator accepts two numbers for addition, or two strings for concatenation.
  • The subtraction ( - ), multiplication ( * ), division ( / ), and modulus ( % ) operators accept two numbers.

Operators that produce strings

  • The period ( . ) operator concatenates both strings and number. Numbers are concatenated in their string represented form.

Operators that produce booleans

  • The AND, OR, NOT, and XOR operators accept two Boolean values.
  • The <>, <=, !=, and == operators accept two numbers or two strings. , !=, and == operators accept two numbers or two strings. The single equal sign ( = ) is a synonym for the double equal sign ( == ).
  • The LIKE operator accepts two strings. This is a pattern match similar to what is used in SQL. For example string LIKE pattern. The pattern operator supports literal text, a percent ( % ) character for a wildcard, and an underscore ( _ ) character for a single character match. For example, field LIKE "a%b_" matches any string starting with a, followed by anything, followed by b, followed by one character.

Functions

You can use the following functions with the eval command.

Category Functions
Comparison and Conditional case, cidrmatch, coalesce, if, like, match, null, nullif, searchmatch, validate
Conversion tonumber, tostring
Cryptographic md5, sha1, sha256, sha512
Date and Time now, relative_time, strftime, strptime, time
Informational isbool, isnotnull, isnull, isnum, isstr, typeof
Mathematical abs, ceil, exact, exp, floor, ln, log, pi, pow, round, sigfig, sqrt
Multivalue commands, mvappend, mvcount, mvdedup, mvfilter, mvfind, mvindex, mvjoin, mvrange, mvsort, mvzip
Statistical max, min, random
Text len, lower, ltrim, replace, rtrim, spath, split, substr, trim, upper, urldecode

For descriptions and examples of each function, see "Evaluation functions".

Usage

General

The eval command requires that you specify a field name that takes the results of the expression you want to evaluate. If this destination field matches a field name that already exists, the values of the field are replaced by the results of the eval expression.

You can also use the value of another field as the name of the destination field by using curly brackets, { }. For example, if you have an event with the following fields, aName=counter and aValue=1234, use | eval {aName}=aValue to return counter=1234.

Numbers and strings can be assigned to fields, while booleans may not be. However you can convert booleans and nulls to strings using tostring(), which may be assigned to fields.

During calculations, numbers are double precision floating point numbers.

  • Operations resulting in NaN assigned to a field, result in "nan".
  • Positive and negative overflow result in "inf" and "-inf".
  • Division by zero result in a null field.

If you are using a search as an argument to the eval command and functions, you cannot use a saved search name; you must pass a literal search string or a field that contains a literal search string (like the 'search' field extracted from index=_audit events).

About calculated fields

You can use eval statements to define calculated fields by defining the eval statement in props.conf. When you run a search, Splunk search evaluates the statements and creates fields in a manner similar to that of search time field extraction. Setting up calculated fields means that you no longer need to define the eval statement in a search string. Instead, you can search on the resulting calculated field directly. For more information and an example, see the section Calculated fields at the end of this topic.

Basic Examples

1. Create a new field that contains the result of a calculation

Create a new field called velocity in each event. Calculate the velocity by dividing the values in the distance field by the values in the time field.

... | eval velocity=distance/time

2. Use the if function to create and populate a status field

Create a field called status in each event. Set the value in the status field to OK if the error value is 200. Otherwise set the status value to Error.

... | eval status = if(error == 200, "OK", "Error")

3. Use the lower function to convert values to lowercase

Create the lowuser field and populate the field with the lowercase versions of the values in the username field.

... | eval lowuser = lower(username)

4. Use the pi and power functions to create a sum of the areas

Set sum_of_areas to be the sum of the areas of two circles.

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

5. Output string values for some common HTTP error codes

Use the case function to evaluate the contents of the error field. For the HTTP error codes specified, add the corresponding string value into the new field error_msg.

... | eval error_msg = case(error == 404, "Not found", error == 500, "Internal Server Error", error == 200, "OK")

6. Concatenate the values from the multiple fields into a new field

Create a new field called full_name and concatenate the first name and surname values, with a space between the two names.

... | eval full_name = first_name." ".surname

This example uses the concatenation operator (the period character) to concatenate the values in the first_name field with the values in the surname field. A space between the two names is created by using quotation marks to specify a string, with a space inside the quotation marks.

7. Display timechart of the avg of cpu_seconds by processor, rounded to 2 decimals

... | timechart eval(round(avg(cpu_seconds),2)) by processor

8. Convert a numeric field value to a string with commas and 2 decimals

If the original value of x is 1000000, use the tostring function to return x as 1,000,000.

... | eval x=tostring(x,"commas")

To include a currency symbol at the beginning of the string, specify the currency symbol as a string before the tostring function. Use the concatenation operator (the period character) to concatenate the currency symbol with x.

... | eval x="$".tostring(x,"commas")

This returns x as $1,000,000.

Use Case Examples

9. Coalesce a field from two different source types, create a transaction of events

This example shows how you might coalesce a field from two different source types and use that to create a transaction of events. The sourcetype=A has a field called number, and sourcetype=B has the same information in a field called subscriberNumber.

sourcetype=A OR sourcetype=B | eval phone=coalesce(number,subscriberNumber) | transaction phone maxspan=2m

The eval command is used to add a common field, called phone, to each of the events whether they are from sourcetype=A or sourcetype=B. The value of phone is defined, using the coalesce() function, as the values of number and subscriberNumber. The coalesce() function takes the value of the first non-NULL field (that means, it exists in the event).

Now, you are able to group events from either source type A or B if they share the same phone value.

10. Separate events into categories, count and display minimum and maximum values

This example uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that contains magnitude (mag), coordinates (latitude, longitude), region (place), etc., for each earthquake recorded.

You can download a current CSV file from the USGS Earthquake Feeds and add it as an input to Splunk.

Earthquakes occurring at a depth of less than 70 km are classified as shallow-focus earthquakes, while those with a focal-depth between 70 and 300 km are commonly termed mid-focus earthquakes. In subduction zones, deep-focus earthquakes may occur at much greater depths (ranging from 300 up to 700 kilometers).

Classify recent earthquakes based on their depth.

source=usgs | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) by Description

The eval command is used to create a field called Description, which takes the value of "Shallow", "Mid", or "Deep" based on the Depth of the earthquake. The case() function is used to specify which ranges of the depth fits each description. For example, if the depth is less than 70 km, the earthquake is characterized as a shallow-focus quake; and the resulting Description is Shallow.

The search also pipes the results of eval into the stats command to count the number of earthquakes and display the minimum and maximum magnitudes for each Description:

Searchref eval usgsex1.1.png

11. Find IP addresses and categorize by network using eval functions cidrmatch and if

This example is designed to use the sample dataset from "Get the tutorial data into Splunk" topic of the Search Tutorial, but it should work with any format of Apache Web access log. Download the data set and follow the instructions in that topic to upload it to Splunk. Then, run this search using the time range Other > Yesterday.

In this search, you're finding IP addresses and classifying the network they belong to.

sourcetype=access_* | eval network=if(cidrmatch("192.0.0.0/16", clientip), "local", "other")

This example uses the cidrmatch() function to compare the IP addresses in the clientip field to a subnet range. The search also uses the if() function, which says that if the value of clientip falls in the subnet range, then network is given the value local. Otherwise, network=other.

The eval command does not do any special formatting to your results -- it just creates a new field which takes the value based on the eval expression. After you run this search, use the fields sidebar to add the network field to your results. Now you can see, inline with your search results, which IP addresses are part of your local network and which are not. Your events list should look something like this:

EvalEx2 events.png


Another option for formatting your results is to pipe the results of eval to the table command to display only the fields of interest to you.

Note: This example just illustrates how to use the cidrmatch 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.

12. Extract information from an event into a separate field, create a multivalue field

This example uses generated email data (sourcetype=cisco_esa). You should be able to run this example on any email data by replacing the sourcetype=cisco_esa with your data's sourcetype value and the mailfrom field with your data's email address field name (for example, it might be To, From, or Cc).

Use the email address field to extract the user's name and domain.

sourcetype="cisco_esa" mailfrom=* | eval accountname=split(mailfrom,"@") | eval from_user=mvindex(accountname,0) | eval from_domain=mvindex(accountname,-1) | table mailfrom, from_user, from_domain

This example uses the split() function to break the mailfrom field into a multivalue field called accountname. The first value of accountname is everything before the "@" symbol, and the second value is everything after.

The example then uses mvindex() function to set from_user and from_domain to the first and second values of accountname, respectively.

The results of the eval expressions are then piped into the table command. You can see the the original mailfrom values and the new from_user and from_domain values in the following results table:

EvalEx4 results.png


Note: This example is really not that practical. It was written to demonstrate how to use an eval function to identify the individual values of a multivalue fields. Because this particular set of email data did not have any multivalue fields, the example creates one (accountname) from a single value field (mailfrom).


13. Categorize events using the match function

This example uses generated email data (sourcetype=cisco_esa). You should be able to run this example on any email data by replacing the sourcetype=cisco_esa with your data's sourcetype value and the mailfrom field with your data's email address field name (for example, it might be To, From, or Cc).

This example classifies where an email came from based on the email address's domain: .com, .net, and .org addresses are considered local, while anything else is considered abroad. (Of course, domains that are not .com/.net/.org are not necessarily from abroad.)

sourcetype="cisco_esa" mailfrom=*| eval accountname=split(mailfrom,"@") | eval from_domain=mvindex(accountname,-1) | eval 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 Example 12. 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 local. If from_domain does not match, location is assigned abroad.

The eval results are then piped into the stats command to count the number of results for each location value and produce the following results table:

EvalEx5 resultsTable.png


After you run the search, you can add the mailfrom and location fields to your events to see the classification inline with your events. If your search results contain these fields, they will look something like this:

EvalEx5 eventsList.png


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.

14. Convert the duration of transactions into more readable string formats

This example uses the sample dataset from the Search Tutorial but should work with any format of Apache Web access log. Download the data set from this topic in the Search Tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

Reformat a numeric field measuring time in seconds into a more readable string format.

sourcetype=access_* | transaction clientip maxspan=10m | eval durationstr=tostring(duration,"duration")

This example uses the tostring() function and the duration option to convert the duration of the transaction into a more readable string formatted as HH:MM:SS. The duration is the time between the first and last events in the transaction and is given in seconds.

The search defines a new field, durationstr, for the reformatted duration value. After you run the search, you can use the Field picker to show the two fields inline with your events. If your search results contain these fields, they will look something like this:

EvalEx4 eventsList.png

15. Calculated fields example

You can use calculated fields to move your commonly used eval statements out of your search string and into props.conf file. Search strings that are added to the props.conf file are processed behind the scenes at search time. With calculated fields, you can change the search from Example 12, above, to:

sourcetype="cisco_esa" mailfrom=* | table mailfrom, from_user, from_domain

In this example, the three eval statements that are in the search--that defined the accountname, from_user, and from_domain fields--are now computed behind the scenes. When the search is run the fields are calculated for any event that contains the extracted field mailfrom field. You can also search on those fields independently after the fields are set up as calculated fields in props.conf. You could search on from_domain=email.com, for example.

For more information about setting calculated fields up in props.conf, see "Define calculated fields" in the Knowledge Manager Manual.

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the eval command.

PREVIOUS
erex
  NEXT
eventcount

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters