Using the Splunk strftime and strptime commands are two important elements for properly dealing with timestamps in indexing and searching for logs in Splunk.
Properly tracking time enables you to extract valuable insights from your data. This could mean identifying trends over time, spotting events that are out of pattern, or identifying when a number of events break an alert threshold over a given period.
The Splunk powerful functions strftime and strptime enable us to precisely query our data for the insights we want. In this post, we will demonstrate the value of these functions and provide examples of several real-world use cases.
Understanding the Splunk strftime Command
Strftime is a Splunk search function that converts a UNIX time value to a human readable format. Splunk uses UNIX time for the contents of the _time field in events. This means that for any date or time-related calculations we want to perform in our searches, we can run the strftime function against the _time field in our data.
UNIX time is a common method for measuring date and time that measures the number of seconds that have elapsed since January 1, 1970. While this is a convenient method for computers to track time, it’s not very helpful for humans, which is why we need strftime.
Proper Command Syntax for strftime
<primary_search>
| eval <new_field>=strftime(<unix_time_field>, "<time_format_variables_to_display>")
Understanding the Splunk strptime Command
Where strftime takes a UNIX time and converts it to human-readable format, strptime does the exact opposite. Strptime takes human-readable timestamps in your data and converts them to UNIX time. This is helpful when you have human-readable timestamps that you need to re-format or use cases that require UNIX time while your data contains human-readable time.
Proper Command Syntax for strptime
<primary_search>
| eval <new_field>=strptime(<time_string_field>, "<time_format_variables_to_read>")
The strftime vs. strptime Commands
Why you should use strftime
Strftime enables handling of date & time information within your Splunk queries. There are two primary benefits to leveraging this capability which we will explore below.
Benefit #1: strftime supports other Splunk time functions:
While the input to the strftime function is often Splunk’s _time field, it doesn’t have to be. The strftime function can also use other Splunk functions as input, such as now() and time(). Because these functions return time in UNIX time format, we must use the strftime format to make this data human-readable. Failing to properly leverage strftime can cause problems. Without it, any timestamps in UNIX time format will display in native UNIX format in your search results. Additionally, the results of functions like now() and time() will not work in calculations that also include human-readable timestamps.
Benefit #2: strftime lets you customize parts of your timestamps:
The strftime function takes two inputs: a timestamp in UNIX time format and format specification. The format specification is used to format your timestamps anyway you want. Additionally, this means that you can extract and reference individual segments of the timestamp, such as the month and day or the hour and minute. The format argument of strftime maps exactly to every element of a timestamp to assist you with complex timestamp parsing. Parsing time data any other way introduces the risk of innaccurate results.
Why you should use strptime
The strptime command in Splunk is essential for accurately converting human-readable timestamps into UNIX time format within your Splunk queries. This command ensures that any date and time information, regardless of its original format, can be consistently and precisely interpreted by Splunk.
There are two primary benefits to leveraging the strptime command’s capabilities, which we will explore in detail below:
Benefit #1: Multiple timestamps can be used in search logic to provide more complex reporting:
The strptime command can be used to extract additional timestamps from data other than Splunk’s default extracted _time field. Any number of unique fields that provide a string representing a time value can be used to calculate new fields with date time values. Using these fields as timestamps in Splunk queries allows you to improve logic for conditional or precise reporting, such as calculating relative time.
Benefit #2: Human-generated data can be easily incorporated into analyses and reporting:
Humans often create data with inconsistent formatting, unlike machines. A common example is the variation in how date/time data is written by hand. The strptime command can use various time format variables to analyze any timestamp written as a string and create a UNIX timestamp value for use in further SPL logic. This allows any data containing time information, such as financial reporting or HR data, to be included in Splunk reports and dashboards.
Splunk Time Variables
There are many different time variables available for use with strftime and strptime. A few examples are below:
| Variable | Description |
|---|---|
| %H | Hour in 24-hour format (range 00-23) |
| %M | Minute as a number (range 00-59) |
| %N | Subsecond digits, such as %3N for milliseconds or %6N for microsoconds |
| %A | Weekday (Sunday, Saturday...) |
| %j | Day of year (001-366) |
| %b | Abbreviated month (Jan, Feb...) |
Sample strftime Use Cases
Below are some example queries that leverage strftime.
Example #1: Create a day of the week field:
When you have numeric data, such as timestamps, response times, or ages, binning allows you to group values into time intervals or age breaks. This simplifies the analysis by creating a clear structure. This query identifies the weekday of the event in question (such as Sunday or Saturday) and assigns it to a new field.
| eval weekday=strftime(_time, "%A")
Example #2: Reference the current day of the month:
This query references the current time (i.e. search-time), identifies the day of the month, and assigns it to a new field.
| eval today=strftime(now(), "%d")
Example #3 Create a timestamp relative to another timestamp:
This query references the event in question, creates a new timestamp at the top of the hour previous to that event, and then creates a human-readable version of the new timestamp using the format supplied.
| eval n=strftime(relative_time(_time, "-1h@h"), "%H:%M:%S")
Sample strptime Use Cases
The scenario below demonstrates the concepts in previous examples by displaying a custom format for the date of each day’s calculated Splunk ingest volume. Splunk’s timechart command, while printing a human-readable timestamp, preserves a UNIX timestamp value in the _time field. The report leverages this field to customize the date format using strftime.
index=_internal sourcetype=splunkd group="per_index_thruput" earliest=-1mon
| eval GB=kb/1024/1024
| timechart per_day(GB)
| rename _time as "Date", per_day(GB) as "GB Indexed"
| eval Date=strftime(Date, "%Y %b %d")
| fillnull value=0
Using the strptime command operates on a chosen field to produce a UNIX time value, but it does have some specific requirements for specificity beyond the examples seen for the strftime command. The field being passed into strptime does have to provide at least a uniquely identifiable day (day, month, and year). While this is often a minimum level of detail in timestamp data, this can be a specific concern with human-generated data.
The example below is searching Microsoft Entra ID logging for configured groups. This report is ingested on a regular schedule to capture the latest state of groups in the tenant, which provides relatively up-to-date timestamps. The data contains another timestamp for the creation date of each group. Using the strftime command, an age can be calculated for each group:
index=mscloud sourcetype="azure:aad:group"
| eval creation_time=strptime(createdDateTime, "%Y-%m-%dT%H:%M:%SZ")
| eval days_since_creation=(_time-creation_time)/86400
| stats latest(days_since_creation) as latest_reported_age by id, displayName
Conclusion
Strftime and strptime are powerful Splunk commands that enable accurate and easily repeatable reference to timestamps. They support a wide variety of time variables in many different formats, so it is easy to customize for your specific needs.
- Enhanced Timestamp Handling with strftime and strptime: The Splunk commands strftime and strptime are crucial for converting between UNIX time and human-readable formats, enabling precise and flexible timestamp handling. These commands facilitate accurate date and time calculations in Splunk queries, making it easier to analyze and interpret time-based data.
- Versatility and Customization: Both commands support a wide range of time variables and formats, offering the ability to tailor timestamp formats to specific requirements. This versatility allows users to extract and reference individual segments of timestamps, improving the accuracy and relevance of data analysis in various use cases.
- Improved Reporting and Analysis: By leveraging strftime and strptime, Splunk users can incorporate diverse timestamp data, including human-generated data, into their analyses and reports. This capability enhances the logic of search queries and supports complex reporting needs, such as calculating relative time and integrating multiple timestamps for more detailed insights.
To access more Splunk searches, check out Atlas Search Library, which is part of the Atlas Platform. Specifically, Atlas Search Library offers a curated list of optimized searches. These searches empower Splunk users without requiring SPL knowledge. Furthermore, you can create, customize, and maintain your own search library. By doing so, you ensure your users get the most from using Splunk.
