Define an automatic lookup in Splunk Web
Manual lookups are applied to the results of a search when they are invoked with the lookup
command. Automatic lookups are applied to all searches at search time.
Splunk software does not support nested automatic lookups.
Add a new lookup to run automatically
Prerequisites
Review the following topics:
- Lookups and the search-time operations sequence for field lookup restrictions
- Define a CSV lookup in Splunk Web
- Define an external lookup in Splunk Web
- Define a KV Store lookup in Splunk Web
- Define a geospatial lookup in Splunk Web
- An example lookup in Splunk Web
A lookup definition that you have defined previously.
Steps
- In Splunk Web, select Settings > Lookups.
- Under Actions for Automatic Lookups, click Add new.
- Select the Destination app.
- Give your automatic lookup a unique Name.
- Select the Lookup table that you want to use in your fields lookup.
This is the name of the lookup definition that you defined on the Lookup Definition page. - In the Apply to menu, select a host, source, or source type value to apply the lookup and give it a name in the named field.
- Under Lookup input fields provide one or more pairs of input fields.
The first field is the field in the lookup table that you want to match. The second field is a field from your events that matches the lookup table field. For example, you can have anip_address
field in your events that matches anip
field in the lookup table. So you would enterip = ip_address
in the automatic lookup definition. - Under Lookup output fields provide one or more pairs of output fields.
The first field is the corresponding field that you want to output to events. The second field is the name that the output field should have in your events. For example, the lookup table may have a field namedcountry
that you may want to output to your events asip_city
. So you would entercountry=ip_city
in the automatic lookup definition.
To avoid creating automatic lookup reference cycles, do not leave the Lookup output fields blank. - Select Overwrite field values to overwrite existing field values in events when the lookup runs. If you do not select this checkbox, the Splunk software does not apply the lookup to events where the output fields already exist.
Note: This is equivalent to configuring your fields lookup inprops.conf
. - Click Save.
The Automatic lookup view appears, and the lookup that you have defined is listed.
If you have selected Overwrite field values, the automatic lookup lists with the keyword OUTPUT in its name. If you do not select Overwrite field values, the automatic lookup lists with OUTPUTNEW in its name.
Avoid creating automatic lookup reference cycles
You will receive error messages for automatic lookup definitions that contain lookup reference cycles. A reference cycle occurs when lookup input and output fields end up being reused, either within the same lookup configuration, or among related lookup configurations.
For example, the following lookup configuration sets up a simple reference cycle where the type
field appears as an input field and an output field. It is a case where the field that you are matching in your events is the same field that you are adding to your events.
LOOKUP-meeting-type meeting_type_lookup object.type as type OUTPUTNEW meeting_type as type
You can accidentally set up more complex reference cycles between two or more related lookup configurations. For example, you might have a situation where multiple lookups combine to have fieldA ← fieldB ← fieldC ← fieldA.
Lookup reference cycles are often accidentally created when the Lookup output fields are left blank during the definition of an automatic lookup. When you leave Lookup output fields blank, the Splunk software uses all of the fields in the lookup table that are not the match fields as implicit output fields. Implicit output fields can easily create situations where the same field names appear in the match and output field sets. It can also set up reference cycles that involve multiple lookup configurations.
For example, say you have a lookup table named columns
that contains five fields: column1
, column2
, column3
column4
, and column5
. Then you set up the following two lookup configurations that both leverage the columns
lookup table:
LOOKUP-col-testA columns column1 as column2 OUTPUT
LOOKUP-col-testB columns column1 as column3 OUTPUTNEW column4, column5 as field5
When you consider that the implicit output fields for LOOKUP-col-testA
are actually all of the fields from the column
lookup table except column1
(meaning column2
, column3
column4
, and column5
), you can see how this can cause these configurations to get tangled up with each other.
This table shows you the lookup reference cycles that different searches will encounter as a result of the way these automatic lookups have been configured:
Search | Reference cycle encountered |
---|---|
column2=*
|
column2 ← column2
|
column3=*
|
column3 ← column2 ← column2
|
field5=*
|
field5 ← column3 ← column2 ← column2
|
Each of these searches returns a lookup reference cycle warning message through the UI. The warning message tells you to inspect search.log for details and update lookup configurations to remove the reference cycle.
Define a time-based lookup in Splunk Web | Lookup example in Splunk Web |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12
Feedback submitted, thanks!