Configure a time-based lookup
If your lookup table has a field that represents time, you can use it to create a time-based lookup. This is also referred to as a temporal lookup. You can configure all four lookup types as time-based lookups.
Simple time-based lookups attempt to match the event timestamp with the timestamp of a record in the lookup table, and then perform operations like adding one or more fields to the event from the matched record.
You can also define time-bounded lookups, which use the event time to define a range of time within which to match lookup records. For example, you could create a time-bounded lookup that matches the first lookup table record with a timestamp that falls within 10 seconds before the event timestamp.
Defining time-based lookups
To create a simple time-based lookup, add the following lines to your lookup stanza in
time_field = <field_name> time_format = <string>
Here are the definitions of these settings.
||Identifies the field in the lookup table that represents the timestamp. The search processor applies the first matching entry in descending order.
|Defaults to an empty string, because lookups are not time-based by default.|
||Specifies the strptime() format of the
This is the Unix epoch time value in seconds (
Defining time-bounded lookups
To create a time bounded lookup, add these optional settings to your time-based lookup configuration:
max_offset_secs = <integer> min_offset_secs = <integer>
Here are the definitions of these settings:
||The maximum amount of time in seconds that an event timestamp can be later than the lookup record timestamp, for a match to occur.|
||The minimum amount of time in seconds that an event timestamp can be later than the lookup record timestamp, for a match to occur.|
min_offset_secs settings define the earliest and latest times within which the search processor can search for matching records in the lookup table. The search processor calculates the earliest and latest time values from the event time like this:
earliest = event timestamp -
latest = event timestamp -
Within this window of time, the search processor applies a match in descending order of time up to the point where we get
max_matches number of matches for that event. If
max_matches is not set, it defaults to
1. For more information about
max_matches see Add field matching rules to your lookup configuration.
Time-based lookup example
Here's an example of a CSV lookup that uses DHCP logs to identify users on a network based on their IP address and the timestamp. The DHCP logs are in a file,
dhcp.csv, which contains the timestamp, IP address, and the user's name and MAC address.
- See about lookups and field actions for more information on lookups.
- See Make your lookup automatic for information on configuring an automatic lookup.
- In a
[dhcpLookup] filename = dhcp.csv time_field = timestamp time_format = %d/%m/%y %H:%M:%S
- In a
props.conffile, make the lookup automatic:
[dhcp] LOOKUP-table = dhcpLookup ip mac OUTPUT user
- Save your file changes.
If you wanted to turn this into a time-bounded lookup, you could add the following settings to the
[dhcpLookup] stanza in
max_offset_secs = 10 min_offset_secs = 0
This would cause the lookup to match events to the first lookup table record with a timestamp that falls within a range of time bounded by the event timestamp and ten seconds before the event timestamp.
Add field matching rules to your lookup configuration
Make your lookup automatic
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.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 8.0.0, 8.0.1, 8.0.2