timechart
Performs search and generates an array of data distributed along a timeline.
Syntax
timechart [<timefield>] [<limit>] [<span>] [<bins>] [<useother>] <functions-expression> ["," <functions-expression>] [<by_expression>]
Required Arguments
functions-expression You must use at least one of the following functions:
| Parameter | Syntax | Description |
|---|---|---|
count | count | count(<field>) | Computes the count of events containing a field. If no field is specified, calculates the total number of events. |
avg | avg(<field>) | Computes the average value for a given field. |
dc | dc(<field>) | Computes the number of unique values in a given field. |
max | max(<field>) | Computes the maximum value for a given field. |
min | min(<field>) | Computes the minimum value for a given field. |
sum | sum(<field>) | Computes the sum of the values in a given field. |
perc | perc(<field>, <percent>) | Calculates the percentile for a specified field and percentage. |
median | median(<field>) | Calculates the median for a specified field. |
Optional Arguments
| Parameter | Syntax | Default | Description |
|---|---|---|---|
span | span=<span> | see predefined span values | Defines the interval for segment distribution. |
timefield | timefield=<field> | @timestamp | The field name where the timestamp is stored. |
bins | bins=<int> | 100 | The maximum number of segments for computation. |
limit | limit=<int> | 10 | The maximum number of unique by_field values that can be used in the column names of the result. Remaining values will be merged into the OTHER field. |
useother | useother=<boolean> | true | If set to false, the limit parameter is ignored. |
by_expression | by <field> | The field name for grouping values. |
The following time formats are allowed: (+|-)<int>(s|m|h|d|w|month):
- s/sec/secs/second/seconds - seconds
- m/min/mins/minute/minutes - minutes
- h/hr/hrs/hour/hours - hours
- d/day/days - days
- w/week/weeks - weeks
- mon/month/months - months
span valuesIf the span parameter is not specified for the time field, predefined parameters will apply.
Here's the list of predefined parameters:
| Time Interval | span |
|---|---|
| last 15 minutes | 10 seconds |
| last 60 minutes | 1 minute |
| last 4 hours | 5 minutes |
| last 24 hours | 30 minutes |
| last 7 days | 1 day |
| last 30 days | 1 day |
| last year | 1 month |
Query Examples
Example 1
Calculating the average number of messages per user by hourly intervals:
... | timechart limit=5 span=1h avg(msgNums) by user
Example 2
In this example, for each unique value of the event.outcome field, data is aggregated over a 15-minute time interval, counting the number of events. The query's time range is divided into 15 intervals.
... | timechart bins=15 span=15m count by event.outcome
For the example input data below, a grouped series bar chart is constructed:
| username | request | path | status | event.outcome |
|---|---|---|---|---|
| Ivanov | GET | /veil | 200 | success |
| Petrov | GET | /cherry | 200 | success |
| Ivanov | POST | /fuel | 403 | failure |
| Andreev | GET | /quilt | 200 | success |
Example 3
Calculating the total number of events and the maximum log offset by 3-hour intervals:
... | timechart span=3h count(log.offset), max(log.offset) by event
Example 4
In this example, for each hourly interval, the system will return the value of the msgNums field that occurs in 95 percent of cases:
... | timechart span=1h perc(msgNums, 95)
Example 5
Dynamics of network traffic response volume for each operating system by 30-minute intervals with a limit on the number of unique hosts:
| timechart span=30m sum(http.response.body.bytes) as 'Объем, КБ' by user_agent.os.full
| eval 'Объем, КБ'=round('Объем, КБ'/1024)
In this example, a new field Volume, KB is created, which converts the values of the http.response.body.bytes field to kilobytes. The round command rounds the kilobytes to 2 significant digits and saves the result into the new Volume, KB field.
For each unique host value user_agent.os.full, the dynamics of the network traffic response volume Volume, KB is calculated for a 30-minute interval.
Example input data:
| user.name | http.response.body.bytes | user_agent.os.full | @timestamp |
|---|---|---|---|
| Ivanov | 50988 | Mac OS X | 2025-05-26T15:25:39.697685Z |
| Petrov | 10772 | Windows 8 | 2025-05-26T15:25:33.003472Z |
| Borisov | 51954 | Windows 10 | 2025-05-26T15:25:24.338701Z |
| Ermolov | 10541 | iPhone OS 4.2.6 | 2025-05-26T15:25:24.290198Z |
| Andreev | 10646 | Android 2.3.3 | 2025-05-26T15:25:25.223198Z |
The query execution result could be the following table:
| Android 2.3.3 | Mac OS X | Windows 10 | Windows 8 | iPhone OS 4.2.6 | @timestamp |
|---|---|---|---|---|---|
| 181 | 300 | 133 | 257 | 136 | 2025-05-26T16:00:00.000Z |
| 230 | 350 | 233 | 237 | 283 | 2025-05-26T16:30:00.000Z |
| 568 | 503 | 388 | 288 | 378 | 2025-05-26T17:00:00.000Z |
