Train Splunk to recognize a timestamp
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Contents
Train Splunk to recognize a timestamp
Splunk recognizes most timestamps by default; for more information read How Splunk extracts timestamps. If Splunk doesn't recognize a particular timestamp, you can use the train dates command to teach Splunk the pattern. The output of train dates is a regular expression that you can add to datetime.xml and props.conf to configure the unique timestamp extraction.
The train command lets you interactively teach Splunk new patterns for timestamps, fields, and sourcetypes. for more information about train and the different arguments you can use with it, refer to the train help page:
./splunk help train
Important: Use train dates only when you can't configure the timestamp with props.conf.
Steps to configure timestamps with train dates
To teach Splunk a new timestamp pattern, complete the following steps:
1. Copy a sampling of your timestamp data into a plain text file.
Splunk learns the pattern of the timestamp based on the patterns in this text file.
2. Run the train dates command.
This feature is interactive. When prompted, provide the path to the text file containing your timestamp data. The command produces a regular expression for your timestamp.
3. Create a custom datetime.xml.
Copy the output of the train command into a copy of datetime.xml file.
Note: The default datetime.xml file is located in $SPLUNK_HOME/etc/datetime.xml. Do not modify this file; instead, copy the default datetime.xml into a custom application directory in $SPLUNK_HOME/etc/apps/ or $SPLUNK_HOME/etc/system/local/. Refer to the User Manual topic about applications for more information.
4. Edit your local props.conf.
Include the path to your custom datetime.xml file in the relevant stanzas.
Note: The following instructions assume that you have set a Splunk environment variable. Otherwise, navigate to SPLUNK_HOME/bin and run Splunk CLI commands with:
./splunk [command]
Run the train dates command
The train command is an interactive CLI tool. For Splunk to learn a new date format, you need to explicitly provide a file and pattern. Afterwards, Splunk returns a string for you to add to datetime.xml.
1. To begin training Splunk to recognize a new timestamp, type:
./splunk train dates
Splunk prompts you for an action:
------------------------------------------------------
What operation do you want to perform? (default=learn)
------------------------------------------------------
Enter choice: [Learn]/Test/Quit >
The default action is Learn.
2. To perform the training operation, type "L", "l", or "learn". Click enter.
Splunk prompts you to give it the sample file you want to use to train it:
Enter full filename from which to learn dates > sampling.txt
3. Enter the path of the file on your Splunk server (this step doesn't allow tab-complete).
Splunk displays the first line of your sample and asks you to teach it the values for the timestamp:
------------------------------------
Interactively learning date formats.
------------------------------------
INSTRUCTIONS: If a sample line does not have a timestamp, hit Enter.
If it does have a timestamp, enter the timestamp separated by commas
in this order: month, day, year, hour, minute, second, ampm, timezone.
Use a comma as a placeholder for missing values. For example, for a
sample line like this "[Jan/1/08 11:56:45 GMT] login", the input
should be: "Jan, 1, 08, 11, 56, 45, , GMT" (note missing AM/PM).
Spaces are optional.
SAMPLE LINE 1:
Tue Jul 10 21:23:06 PDT 2007 Received Trade 330 with detail user: user3456 date: date: 10Jul200721:
23:06 action: sell 3583 MNAG @ 42
--------------------------------------------------------------------------------
Enter timestamp values as: month, day, year, hour, minute, second, ampm, timezone.
> 7, 10, 2007, 9, 23, 06, pm, PDT
4. Enter values for month, day, year, hour, minute, second, ampm, and timezone (as shown above). This trains Splunk to recognize the values you enter as the designated portions of the timestamp.
If the values are sufficient, Splunk displays:
Learned pattern. ---------------------------------------------------------------------------------- If you are satisfied that the timestamps formats have been learned, hit control-c. ----------------------------------------------------------------------------------
5. After you hit control-c, Splunk displays:
Patterns Learned.
It is highly recommended that you make changes to a copy of the default datetime.xml file.
For example, copy "/Applications/splunk/etc/datetime.xml" to "/Applications/splunk/etc/system/local/datetime.xml", and work with that file.
In that custom file, add the below timestamp definitions, and add the pattern names
to timePatterns and datePatterns list.
For more details, see http://www.splunk.com/doc/latest/admin/TrainTimestampRecognition
--------------------------------------------------------------------------------
<define name="trainwreck_1_date" extract="day,litmonth,year,">
<text><![CDATA[:\d+\s\w+\s(\d+)\s(\w+)\s(\d+)]]></text>
</define>
<define name="trainwreck_1_time" extract="hour,minute,second,ampm,">
<text><![CDATA[(\d+):(\d+):(\d+)\s(\w+)]]></text>
</define>
------------------------------------------------------
What operation do you want to perform? (default=learn)
------------------------------------------------------
Enter choice: [Learn]/Test/Quit > q
6. Check the output.
- If it's correct, quit. Then, copy the output and continue to the next section.
- If it's not correct, enter the Learn choice to re-train Splunk.
Create a custom datetime.xml
After running train, Splunk outputs a string describing the new timestamp pattern.
In your custom datetime.xml file:
1. Paste the string returned from train before the <timePatterns> and <datePatterns> stanzas.
2. Add <use name="define name"/> for both <timePatterns> and <datePatterns> with the string defined as the <define name="string".
Example:
For the following train dates output:
<define name="_utcepoch" extract="utcepoch">
<text><![CDATA[((?<=^|[\s#,"=\(\[\|\{])(?:1[01]|9)\d{8}|^@[\da-fA-F]{16,24})(?:\d{3})?(?![\d\(])]]></text>
</define>
The modified datetime.xml file might look something like:
<define name="_utcepoch" extract="utcepoch">
<text><![CDATA[((?<=^|[\s#,"=\(\[\|\{])(?:1[01]|9)\d{8}|^@[\da-fA-F]{16,24})(?:\d{3})?(?![\d\(])]]></text>
</define>
<timePatterns>
<use name="_time"/>
<use name="_hmtime"/>
<use name="_hmtime"/>
<use name="_dottime"/>
<use name="_combdatetime"/>
<use name="_utcepoch"/>
</timePatterns>
<define name="_utcepoch" extract="utcepoch">
<text><![CDATA[((?<=^|[\s#,"=\(\[\|\{])(?:1[01]|9)\d{8}|^@[\da-fA-F]{16,24})(?:\d{3})?(?![\d\(])]]></text>
</define>
<datePatterns>
<use name="_usdate"/>
<use name="_isodate"/>
<use name="_eurodate"/>
<use name="_bareurlitdate"/>
<use name="_orddate"/>
<use name="_combdatetime"/>
<use name="_masheddate"/>
<use name="_masheddate2"/>
<use name="_utcepoch"/>
</datePatterns>
Edit your local props.conf
To apply your custom timestamp, Splunk needs to know where to find your new datetime.xml.
Modify props.conf to:
1. Add a DATETIME_CONFIG key to the timestamp configuration stanzas.
2. Set the value of DATETIME_CONFIG to the path of your custom datetime.xml.
Note: See all of the keys you can set in a stanza to configure timestamp recognition.
Example:
This example applies a custom datetime.xml to events from the host, "london".
[host::london] DATETIME_CONFIG = /etc/system/local/datetime.xml
You can set custom timestamp extraction patterns for any host, source, or sourcetype by editing props.conf.
This documentation applies to the following versions of Splunk: 3.4 , 3.4.1 , 3.4.2 , 3.4.3 , 3.4.5 , 3.4.6 , 3.4.8 , 3.4.9 , 3.4.10 , 3.4.11 , 3.4.12 , 3.4.13 , 3.4.14 View the Article History for its revisions.