Draw a Time Chart where the x-axis is time. Time is grouped into buckets.

ParameterTypeRequiredDefaultDescription
bucketsnumberoptional[a]  Defines the number of buckets. The time span is defined by splitting the query time interval into this many buckets.
  Minimum0 
  Maximum1500 
functionArray of Aggregate Functionsoptional[a]count() Specifies which aggregate functions to perform on each group.
limitnumberoptional[a]10 Defines the maximum number of series to produce. A warning is produced if this limit is exceeded, unless the parameter is specified explicitly.
  Maximum500 
minSpanstringoptional[a]auto Defines the time span for each bucket. The time span is defined as a Relative Time Syntax such as 1hour or 3 weeks. If not provided or set to auto, the search time interval —and thus the number of buckets— is determined dynamically.
  Valid Values
   1dayTimespan set using Relative Time Syntax
   autoAutomatically determine the time span for each bucket
series[b]stringoptional[a]  Each value in the field specified by this parameter becomes a series on the graph.
spanstringoptional[a]auto Defines the time span for each bucket. The time span is defined as a Relative Time Syntax like 1hour or 3 weeks. If not provided or set to auto, the search time interval —and thus the number of buckets— is determined dynamically.
timezonestringoptional[a]  Defines the time zone for bucketing. This value overrides timeZoneOffsetMinutes which may be passed in the HTTP/JSON query API. For example: timezone=UTC or timezone='+02:00'.
unitstringoptional[a]No conversion Each value is a unit conversion for the given column. For instance: bytes/span to Kbytes/day converts a sum of bytes into Kb/day automatically taking the time span into account. If present, this array must be either length 1 (apply to all series) or have the same length as the function parameter. See the reference at Relative Time Syntax.

[a] Optional parameters use their default value unless explicitly set

[b] The argument name series can be omitted.

Omitted Argument Names

The argument name for series can be omitted; the following forms of this function are equivalent:

logscale
timeChart("value")

and:

logscale
timeChart(series="value")

timeChart() Examples

  • Show the number of events per hour over the last 24 hours. We do this by selecting to search over the last 24 hours in the time selector in the UI, and then we tell the function to make each time bucket one hour long (withspan=1hour):

    logscale
    timeChart(span=1h, function=count())

    The above creates 24 time buckets when we search over the last 24 hours, and all searched events get sorted into groups depending on the bucket they belong to (based on their @timestamp value). When all events have been divided up by time, the count() function is run on each group, giving us the number of events per hour.

    Note

    Even without specifying count(), the query equally returns the number of events for each hour, because count() is the default function used when you don't specify a function manually, as in:

    logscale
    timeChart(span=1h)

  • Instead of counting all events together, you can also count different kinds of events. For example, you may want to count different kinds of HTTP methods used for requests in the logs. If those are stored in a field named method, you can use this field as a series:

    logscale
    timeChart(span=1h, function=count(), series=method)

    Instead of having one group of events per time bucket (as in the previous example), we will now get multiple groups: one group for every value of method that exists in the timespan we're searching in. So if we are still searching over a 24 hour period, and we have received only GET, PUT, and POST requests in that timespan, we will get three groups of events per bucket (because we have three different values for method).

    This means we end up with 72 groups of events. And every group contains only events which correspond to some time bucket and a specific value of method. Then count() is run on each of these groups, to give us the number of GET events per hour, PUT events per hour, and POST events per hour.

    Counting Events Divided into Buckets

    Figure 107. Counting Events Divided Into Buckets


  • Show the number of different HTTP methods by dividing events into time buckets of 1 minute and counting the HTTP methods (GET, POST, PUT etc). As in the previous example, the timechart will have a line for each HTTP method.

    logscale
    timechart(span=1min, series=method, function=count())

  • Use the number of buckets —instead of the time span — to show the number of different HTTP methods over time:

    logscale
    timechart(buckets=1000, series=method, function=count())

  • Get a graph with the response time percentiles:

    logscale
    timechart(function=percentile(field=responsetime, percentiles=[50, 75, 90, 99, 99.9]))

  • Use coda hale metrics to print rates of various events once per minute. Such lines include 1-minute average rates m1=N where N is some number. This example displays all such meters (which are identified by the field name), converting the rates from events/sec to Ki/day.

    logscale
    type=METER rate_unit=events/second
| timechart(name, function=avg(m1), unit="events/sec to Ki/day", span=5m)

  • Upon completion of every LogScale request, we issue a log entry which (among other things) prints the size=N of the result. When summing such size's you would need to be aware of the span, but using a unit conversion, we can display the number in Mbytes/hour, and the graph will be agnostic to the span.

    logscale
    timechart(function=sum(size), unit="bytes/bucket to Mbytes/hour", span=30m)