Configure advanced timestamp recognition with datetime.xml
The Splunk platform uses the datetime.xml timestamp recognition file to extract dates and timestamps from events as it indexes them. The file contains regular expressions that describe how the Splunk platform is to perform those extractions from the raw event data.
In nearly all cases, you do not need to make modifications to the datetime.xml file. In those cases where you do make modifications to the file, you must take care in ensuring the its structure remains intact and that there are no typos, as this can cause significant problems with timestamp recognition.
If you need to modify this file on a Splunk Cloud Platform instance, file a support ticket. It is not possible to modify the file on a Splunk Cloud Platform instance directly. Instead, consider whether or not you need to modify the file at all. Configure the file, if necessary, on a universal or heavy forwarder on the machine that contains the data that you want to send to Splunk Cloud Platform.
On Splunk Enterprise, consider using the props.conf configuration file to configure timestamp recognition
In most cases, you do not need to make changes to the datetime.xml timestamp recognition file on Splunk Enterprise instances. The props.conf configuration file is responsible for most timestamp configuration changes.
When you configure timestamp recognition with the props.conf file, Splunk Enterprise uses the datetime.xml file to configure its timestamp processor and extract timestamps out of the events for the source, source type, or host information in your data. If the software can't process the timestamps in your event data, you can configure Splunk Enterprise to extract the timestamps by making a custom version of the datetime.xml file.
Structure of the datetime.xml file
The datetime.xml file has the following parts:
- Code blocks that define individual elements of a time stamp
- Code blocks with other elements defined within the file
- Extraction pattern code blocks
Each definition code block has one or more <text>
definitions that contain a regular expression that Splunk Enterprise uses to extract the timestamp element.
Code blocks that define individual elements of a time stamp
These individual elements can contain information such as year, month, day, hour, and minute. The following example code block defines the regular expression that Splunk Enterprise uses to extract a literal month element (for example, Jan
, Mar
) out of event data:
<define name="_litmonth" extract="litmonth"> <text><![CDATA[(?<![\d\w])(jan|\x{3127}\x{6708}|feb|\x{4E8C}\x{6708}|mar|\x{4E09}\x{6708}|apr|\x{56DB}\x{6708}|may|\x{4E94}\x{6708}|jun|\x{516D}\x{6708}|jul|\x{4E03}\x{6708}|aug|\x{516B}\x{6708}|sep|\x{4E5D}\x{6708}|oct|\x{5341}\x{6708}|nov|\x{5341}\x{3127}\x{6708}|dec|\x{5341}\x{4E8C}\x{6708})[a-z,\.;]*]]></text> </define>
Code blocks with other elements defined within the file
The following example code block defines the _time
element, which extracts hours, minutes, seconds, subseconds, period of day, and time zone:
<define name="_time" extract="hour, minute, second, subsecond, ampm, zone"> <text><![CDATA[(?<!\d)]]></text> <use name="_hour"/> <text><![CDATA[:]]></text> <use name="_minute"/> <text><![CDATA[:]]></text> <use name="_second"/> <text><![CDATA[(?:(?: \d{4})?[:,\.](\d+))? {0,2}]]></text> <use name="_ampm"/> <text><![CDATA[ {0,2}]]></text> <use name="_zone"/> <text><![CDATA[(?!:\d)]]></text> </define>
Extraction pattern code blocks
Extraction pattern code blocks define the order in which to attempt extracting times and dates from incoming event data. In general, the timePatterns
block defines the order in which the Splunk platform attempts to extract a timestamp under most conditions, and the datePatterns
block defines how to extract dates.
While extraction code blocks in general define when the Splunk platform attempts timestamp extraction, they do not strictly dictate when timestamp extraction occurs. If, for example, there are multiple matches for a timestamp, the platform uses heuristics that favor matches that contain more information or that occur earlier in the event to determine when to perform an extraction.
Create or modify a custom datetime.xml file
In nearly all cases, you do not need to modify the datetime.xml file. Instead, configure the props.conf configuration file for timestamp extractions. See the section Edit timestamp properties in the props.conf configuration file of Configure timestamp recognition for instructions.
If Splunk Enterprise does not extract dates and times properly with the props.conf file, you might need to modify or substitute datetime.xml with a custom version. You can use the splunk train
CLI command to sample the timestamp data and generate code that you can use to create a custom datetime.xml that extracts your timestamp.
The splunk train
CLI command is deprecated, but is still available to help you create patterns for datetime.xml based on your sample timestamp data.
After you create a pattern file with splunk train
, you can make a copy of the default datetime.xml file and add your modifications to it, or you can create a new datetime.xml that only contains your custom timestamp definitions.
Never make modifications directly to $SPLUNK_HOME/etc/datetime.xml. Splunk Enterprise overwrites this file any time you upgrade, and any errors in the file that occur as the result of your changes can cause serious, lasting problems with data ingestion for both your custom source type and all other source types on the instance. If you want to make changes to the default file, save a copy to $SPLUNK_HOME/etc/system/local and make the changes there.
To create or modify a custom datetime.xml file, follow these high-level steps:
- Create a sample timestamp pattern file.
- Run the splunk train CLI command against the file.
- Use the output to create a custom datetime.xml file.
- Reference the custom datetime.xml file in your timestamp configuration.
Create a sample timestamp pattern file
- From a prompt or PowerShell window, create a text file.
- Paste the sample of your timestamp data into this file.
- Save the file and close it.
- Change to the $SPLUNK_HOME/bin directory.
Run the splunk train CLI command against the file
- Change to the $SPLUNK_HOME/bin directory:
cd $SPLUNK_HOME/bin
- Run the
splunk train
CLI command:
./splunk train dates
- After the software asks the action you want to perform, type
L
,l
, orlearn
to perform the "learn" action. - Enter the path to the file that contains the timestamp sample.
Splunk Enterprise displays the first line of your sample and prompts you to enter values that represent 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. >
- Enter values for month, day, year, hour, minute, second, period of day (am/pm), and time zone.
If the values are sufficient, Splunk software displays the following message to show it remembered the pattern:
Learned pattern. ---------------------------------------------------------------------------------- If you are satisfied that the timestamps formats have been learned, hit control-c. ----------------------------------------------------------------------------------
- If Splunk Enterprise correctly learned the timestamp formats, press Ctrl+C.
Splunk software displays text similar to the following:
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="mycustom_date" extract="day,litmonth,year,"> <text><![CDATA[:\d+\s\w+\s(\d+)\s(\w+)\s(\d+)]]></text> </define> <define name="mycustom_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 >
- Review the pattern definitions in the output. If the definition for your timestamp sample looks the way that you want, quit the
splunk train
session by typingQ
,q
, orquit
. Otherwise, type inL
,l
, orlearn
again to attempt the training operation again.
Use the output to create a custom datetime.xml file
After you successfully train Splunk Enterprise to understand your custom timestamp, you must add the definition that splunk train
generated to a custom version of datetime.xml.
You can create this file using the following options:
- Add your timestamp definitions to an existing datetime.xml. This is the preferred method.
- Create a new datetime.xml file that contains only your customized timestamp definitions. This option is better when the source type for your data is in a very strict format and Splunk Enterprise was incorrectly choosing a broader default format.
Never make edits to $SPLUNK_HOME/etc/datetime.xml. Always make a copy of this file and add your custom timestamp patterns to the copy.
- Make a copy of datetime.xml in the $SPLUNK_HOME directory.
cd $SPLUNK_HOME/etc cp datetime.xml system/local/
- Open $SPLUNK_HOME/etc/system/local/datetime.xml for editing.
- On its own line, copy the block of code that the
splunk train
command generated and that begins withdefine name
into the file. This code block can go anywhere between the<datetime>
and<timePatterns>
entries. - Within the
<timePatterns>
block, add a line that references the definition line you added earlier in the datetime.xml file. - Within the
<datePatterns>
code block, add the same line you added in the previous step. - Save the custom datetime.xml file and close it.
See Examples of custom datetime.xml configuration later in this topic for examples.
Reference the custom datetime.xml file in your timestamp configuration
After you build your custom datetime.xml file, you can reference it in props.conf to extract your custom timestamps. You can set a custom timestamp extraction pattern for any host, source, or source type.
- In $SPLUNK_HOME/etc/system/local, create props.conf if it does not already exist.
- Open props.conf in $SPLUNK_HOME/etc/system/local for editing.
- Add a stanza for the host, source, or source type that requires the custom timestamp extraction, if it does not already exist.
- Within this stanza, add a
DATETIME_CONFIG
setting that points to the custom datetime.xml, relative to the $SPLUNK_HOME directory. For example:
[mysourcetype] DATETIME_CONFIG = /etc/system/local/datetime.xml MAX_TIMESTAMP_LOOKAHEAD = 128 MAX_DAYS_AGO = 28
- Repeat the previous steps as necessary for other hosts, sources, or source types that require the custom extraction.
- Save props.conf and close it.
- Restart Splunk Enterprise.
- Confirm that timestamps are being extracted properly for the events that match the host, source, or source type that contains the custom timestamp extraction pattern.
Examples of custom datetime.xml configuration
The following blocks of code are examples of how to properly configure a custom datetime.xml file.
For example, suppose that the splunk train
command generated the following code:
<define name="mycustom_date" extract="day,litmonth,year,"> <text><![CDATA[:\d+\s\w+\s(\d+)\s(\w+)\s(\d+)]]></text> </define> <define name="mycustom_time" extract="hour,minute,second,ampm,"> <text><![CDATA[(\d+):(\d+):(\d+)\s(\w+)]]></text> </define>
See the Example 1a and Example 1b sections for ways you can proceed from this code. Then, see the Example 2 section for the next step.
Example 1a: Modification of existing datatime.xml
Proceeding the previous example, you can then add these definition blocks to an existing datetime.xml in $SPLUNK_HOME/etc/system/local that you copied previously:
<datetime> <define name="mycustom_date" extract="day,litmonth,year,"> <text><![CDATA[:\d+\s\w+\s(\d+)\s(\w+)\s(\d+)]]></text> </define> <define name="mycustom_time" extract="hour,minute,second,ampm,"> <text><![CDATA[(\d+):(\d+):(\d+)\s(\w+)]]></text> </define> <... existing configurations removed for clarity ...> <timePatterns> <use name="_time"/> <use name="_hmtime"/> <use name="_hmtime"/> <use name="_dottime"/> <use name="_combdatetime"/> <use name="_utcepoch"/> <use name="_combdatetime2"/> <use name="mycustom_time"/> </timePatterns> <datePatterns> <use name="_usdate1"/> <use name="_usdate2"/> <use name="_isodate"/> <use name="_eurodate1"/> <use name="_eurodate2"/> <use name="_bareurlitdate"/> <use name="_orddate"/> <use name="_combdatetime"/> <use name="_masheddate"/> <use name="_masheddate2"/> <use name="_combdatetime2"/> <use name="mycustom_date"/> </datePatterns> </datetime>
Example 1b: New datetime.xml with only your timestamp configuration
Instead of the example shown in the Example 1a section, you can also create a new datetime.xml file in $SPLUNK_HOME/etc/system/local, as follows:
<datetime> <define name="mycustom_date" extract="day,litmonth,year,"> <text><![CDATA[:\d+\s\w+\s(\d+)\s(\w+)\s(\d+)]]></text> </define> <define name="mycustom_time" extract="hour,minute,second,ampm,"> <text><![CDATA[(\d+):(\d+):(\d+)\s(\w+)]]></text> </define> <timePatterns> <use name="mycustom_time"/> </timePatterns> <datePatterns> <use name="mycustom_date"/> </datePatterns> </datetime>
Example 2: Reference of new datetime.xml in props.conf for your custom source type
After completing the previous examples, you can then reference the custom datetime.xml file in the configuration for your source type in props.conf, as follows:
$SPLUNK_HOME/etc/system/local/props.conf
[my_custom_sourcetype] DATETIME_CONFIG=/etc/system/local/datetime.xml SHOULD_LINEMERGE=false NO_BINARY_CHECK=true
Configure timestamp assignment for events with multiple timestamps | Specify time zones for timestamps |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!