Splunk® Enterprise

Knowledge Manager Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Use field lookups to add information to your events

Splunk's lookup feature lets you reference fields in an external CSV file that match fields in your event data. Using this match, you can enrich your event data by adding more searchable fields to them. You can base your field lookups on any field, including a temporal field, or on the output of a Python script.

This topic discusses how to use the Lookups manager page, located in Splunk Web, at Manager > Lookups, to:

  • List existing lookup tables or upload a new file.
  • Edit existing lookup definitions or define a new file-based or external lookup.
  • Edit existing automatic lookups or configure a new lookup to run automatically.

For more details about lookups, see "Configure field lookups" in this manual.

List existing lookup tables or upload a new file

View existing lookup table files in Manager > Lookups > Lookup table files, or click "New" to upload more CSV files to use in your definitions for file-based lookups.

Note: CSV files with Pre-OSX OS9 and earlier "Classic Macintosh"-style line endings (aka just a carriage return, "\r") are not supported.

To upload new files:

1. Select a Destination app.

This tells Splunk to save your lookup table file in the app's directory: $SPLUNK_HOME/etc/users/<username>/<app_name>/lookups/.

2. Give your lookup table file a Name.

This will be the name you use to refer to the file in a lookup definition.

3. Browse for the CSV file to upload.

4. Click Save.

Edit existing lookup definitions or define a new file-based or external lookup

Use the Manager > Lookups > Lookup definitions page to define the lookup table or edit existing lookup definitions. You can specify the type of lookup (file-based or external) and whether or not it is time-based. Once you've defined the lookup table, you can invoke the lookup in a search (using the lookup command) or you can configure the lookup to occur automatically.

Note: This is equivalent to defining your lookup in transforms.conf.

Configure a time-based lookup

File-based and external lookups can also be time-based (or temporal), if the field matching depends on time information (a field in the lookup table that represents the timestamp).

To Configure a time-based lookup, specify the Name of the time field. You can also specify a strptime format for this time information and offsets for the time matching.

Include advanced options

Under Advanced options, you can specify:

  • The minimum number of matches for each input lookup value.
  • The maximum number of matches for each input lookup value.
  • A default value to output if fewer than the minimum number of matches are present for a given input.

Edit existing automatic lookups or configure a new lookup to run automatically

Instead of invoking the lookup command when you want to apply a fields lookup to your events, you can set the lookup to run automatically. Use the Manager > Lookups > Automatic lookups page to edit or configure automatic lookups:

1. Select the lookup table file that you want use in your fields lookup.

2. Select a host, source, or sourcetype value to apply the lookup.

3. Under lookup input fields, list one or more pairs of lookup field name and local field name.

4. Under lookup output fields, list one or more pairs of lookup field name and local field name.

5. You can also choose to overwrite the field values each time the lookup runs.

Note: This is equivalent to configuring your fields lookup in props.conf.

Example of HTTP status lookup

This examples walks through defining a static lookup that adds two informational fields, status_description and status_type, into your Web access events. This lets you search for the events you want when you might not know the specific error code. For example, instead of searching for all the server error codes, you can use status="Server Error".

Upload the lookup table to Splunk

1. Download the http_status.csv file:

http_status.csv

Here's a sampling of the file:

status,status_description,status_type
100,Continue,Informational
101,Switching Protocols,Informational
200,OK,Successful
201,Created,Successful
202,Accepted,Successful
203,Non-Authoritative Information,Successful
...

2. Go back to the Search app, and select Manager from the navigation menu on the upper right.

Manager from search.png

3. In the Manager > Lookups view, select Add new for Lookup table files.

Add new lookup file.png

4. In Manager > Lookups > Lookup table files > Add new,

  • Select search for the destination app.
  • Browse for the CSV file that you downloaded earlier.
  • Name the lookup table http_status.
  • Click Save.

Upload http status 4.2.png

After Splunk saves the file, it takes you to the following view:

Upload lookup table file.png

Now, let's go back to the Manager > Lookups view. To do this, click on the Lookups link in the page's breadcrumb. You can always use this to navigate back to a previous view.

Back to manager lookups.png

Define the lookup

1. From Manager > Lookups, select Add new for Lookup definitions.

In the Manager > Lookups > Lookup definitions > Add new view:

Manager add new lookup definition.png

2. Select search for the Destination app.

3. Name your lookup definition http_status.

4. Select File-based under Type.

5. Click Save.

After Splunk saves your lookup definition, it takes you to the following view:

Lookup def saved.png

Notice there are some actions you can take on your lookup definition. Permissions lets you change the accessibility of the lookup table. You can Disable, Clone, and Move the lookup definition to a different app. Or, you can Delete the definition.

Once you define the lookup, you can use the lookup command to invoke it in a search or you can configure the lookup to run automatically.

Set the lookup to run automatically

1. Return to the Manager > Lookups view and select Add new for Automatic lookups.

In the Manager > Lookups > Automatic lookups view:

Add new automatic lookup.png

2. Select search for the Destination app.

3. Name the lookup http_status.

4. Select http_status from the Lookup table drop down.

5. Apply the lookup to the sourcetype named access_combined.

Apply lookup to field.png

6. Lookup input fields are the fields in our events that you want to match with the lookup table. Here, both are named status (the CSV column name goes on the left and the field that you want to match goes on the right):

Lookup input fields.png

7. Lookup output fields are the fields from the lookup table that you want to add to your events: status_description and status_type. The CSV column name goes on the left and the field that you want to match goes on the right.

Lookup output fields.png

8. Click Save.

Auto lookup saved 4.2.png

PREVIOUS
About lookups and workflow actions
  NEXT
Configure field lookups

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18


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