×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
BMC TrueSight IT Data Analytics 11.0 ... Using Search commands

timechart search command

This command creates a time-series representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified.

You can run this command with:

  • Time span in days, minutes, or hours
  • Aggregate functions such as count, sum, or average

The starting and ending points to create the chart are defined by the time range used before you run the command. The time span defined as a part of the command acts as a bucketing option to specify the number of buckets into which you want to divide the data to plot a data point.

You can perform advanced analysis by running this command to group data by a field so that each distinct value of the field acts as an additional grouping. For example, you can plot the count of data occurring from a particular host depending on the data-collector names for the time span specified.

This topic contains the following information:

For a list of all search commands, see Search commands.

Related topics

stats search command

Getting started with search

Syntax

timechart span=<duration><timescale> <aggregate-function>+

timechart span=<duration><timescale> (<aggregate-function> [as <alias>])+

timechart span=<duration><timescale> (<aggregate-function> [as <alias>])+ [by <field>]

In the preceding syntax, the following definitions apply:

  • + indicates one or more similar expressions separated by a comma (,) or space.
  • [expression] indicates it is optional.

  • <duration> refers to an integer value to indicate the time-span bucket.

  • <timescale> refers to a time scale such as days, hours, or minutes.

    The following table describes the time scale options that can be used in the command syntax:

    ItemSyntax
    Minutesm | min | mins | minute | minutes
    Hoursh | hr | hrs | hour | hours
    Daysd | day | days

  • <aggregate-function> refers to the aggregate function used for creating the chart; for example, count, sum, or average.

    The following table describes the aggregate functions that can be used in the command syntax:

    Function SyntaxDescription
    Count
    count (<field>)
    		Uses field name as an argument and returns the number of occurrences of that field in the search results.
    Sum
    sum (<field>)
    		Uses field name as an argument and returns the sum of values of that field in the search results.
    Average
    avg (<field>)
    		Uses field name as an argument and returns the average of values of that field in the search results.
    Minimum
    min (<field>)
    		Uses field name as an argument and returns the smallest value of that field in the search results.
    Maximum
    max (<field>)
    		Uses field name as an argument and returns the highest value of that field in the search results.
    Standard deviationstddev (<field>)Uses field name as an argument and returns the standard deviation of the values of that field in the search results.
    where, <field> can be a field name or a tag name.
  • [as <alias>] refers to the as parameter used for optionally renaming a field with an alternate field name (an alias).
  • by <field> refers to the group by parameter optionally used in conjunction with the aggregate functions to group the result set by the specified field.

Short examples

Example 1: Display a table of statistics (and a multiseries chart) displaying an aggregation of the distinct HOST field values against each day.

... | timechart span=1d count(HOST) by HOST

Example 2: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour.

... | timechart span=1hr count(RequestType)

Example 3: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour and grouped by the ClientIp field. Also, rename the field RequestType to NumberOfRequestTypes.

... | timechart span=1hr count(RequestType) as NumberOfRequestTypes by ClientIp

Example 4: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus a sum and average of the ResponseSize field values.

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize)

Example 5: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus the sum and average of the ResponseSize field values, grouped by the ClientIP field.

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize)
by ClientIp

Example 6: Display the minimum (smallest), maximum (highest), average, and standard deviation of the ResponseSize field values, grouped by the ClientIp field.

... | timechart span=1h min(ResponseSize), max(ResponseSize), avg(ResponseSize),
stddev(ResponseSize) by ClientIp

Example 7: Display the minimum (smallest), maximum (highest), average, and standard deviation of the ResponseSize field values.
... | timechart span=1h min(ResponseSize), max(ResponseSize), avg(ResponseSize),
stddev(ResponseSize)

 

Long examples

The following sample data and sample indexed data (displayed on the Search tab) will help you understand the examples of using the timechart command.

Sample data

10.1.1.140 - - [11/Jul/2013:15:01:52 -0700] "GET /themes/ComBeta/images/bullet.png 
HTTP/1.1" 404 100
10.1.1.140 - - [11/Jul/2013:15:02:52 -0700] "GET /themes/ComBeta/images/bullet.png 
HTTP/1.1" 201 150
10.1.1.141 - - [11/Jul/2013:15:03:52 -0700] "PUT /themes/ComBeta/images/bullet.png 
HTTP/1.1" 201 200
10.1.1.141 - - [11/Jul/2013:15:04:52 -0700] "POST /themes/ComBeta/images/bullet.png 
HTTP/1.1" 200 100

Back to examples ↑

Sample indexed data

10.1.1.141 - - [11/Jul/2013:15:04:52 -0700] "POST /themes/ComBeta/images/bullet.png 
HTTP/1.1" 200 100
HOST=local.bmc.com |ResponseSize=100|COLLECTOR_NAME=u4 |ClientIp=10.1.1.141 |ResponseCode=200 |
RequestType=POST|RequestURL=/themes/ComBeta/images/bullet.png
10.1.1.141 - - [11/Jul/2013:15:03:52 -0700] "PUT /themes/ComBeta/images/bullet.png 
HTTP/1.1" 201 200
HOST=local.bmc.com |ResponseSize=200|COLLECTOR_NAME=u4 |ClientIp=10.1.1.141 |ResponseCode=201 |
RequestType=PUT|RequestURL=/themes/ComBeta/images/bullet.png
10.1.1.140 - - [11/Jul/2013:15:02:52 -0700] "GET /themes/ComBeta/images/bullet.png 
HTTP/1.1" 201 150
HOST=local.bmc.com |ResponseSize=150|COLLECTOR_NAME=u4 |ClientIp=10.1.1.140 |ResponseCode=201 |
RequestType=GET|RequestURL=/themes/ComBeta/images/bullet.png
10.1.1.140 - - [11/Jul/2013:15:01:52 -0700] "GET /themes/ComBeta/images/bullet.png 
HTTP/1.1" 404 100
HOST=local.bmc.com |ResponseSize=100|COLLECTOR_NAME=u4 |ClientIp=10.1.1.140 |ResponseCode=404 |
RequestType=GET|RequestURL=/themes/ComBeta/images/bullet.png

Back to examples ↑

count

In this example, you use the command to see a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour.

Command

... | timechart span=1hr count(RequestType)

Output

Timestampcount(RequestType)
Jul 11 2013 03:00 PM9

Back to examples ↑

count with by parameter

In this example, you use the command to see a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour and grouped by the ClientIp field.

Command

... | timechart span=1hr count(RequestType) by ClientIp

Output

Timestamp10.1.1.140:count
(RequestType)		10.1.1.141:count
(RequestType)		10.1.1.142:count
(RequestType)		10.1.1.143:count
(RequestType)
Jul 11 2013 03:00 PM1111
Jul 11 2013 04:00 PM0000

Back to examples ↑

count, sum, and avg

In this example, you use the command to see a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus a sum and average of the ResponseSize field values.

Command

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize)

Output

Timestampcount
(RequestType)		sum
(ResponseSize)		avg
(ResponseSize)
Jul 11 2013 03:00 PM000
Jul 11 2013 04:00 PM4550137.5

Back to examples ↑

count, sum, and avg with by parameter

In this example, you use the command to see a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus the sum and average of the ResponseSize field values, grouped by the ClientIP field.

Command

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize) 
by ClientIp

Output

Timestamp

10.1.1.141
:count
(Request
Type)		10.1.1.141
:sum
(Response
Size)		10.1.1.141
:avg
(Response
Size)		10.1.1.140
:count
(Request
Type)		10.1.1.140
:sum
(Response
Size)		10.1.1.140
:avg
(Response
Size)
Jul 11 2013 12:00 AM23001502250125

Back to examples ↑

min

In this example, you use the command to display the minimum value (smallest value) of the ResponseSize field.

Command

... | timechart span=1hr min(ResponseSize)

Output

Timestamp

Min
(Response
Size)
Jul 11 2013 12:00 AM100

Back to examples ↑

max

In this example, you use the command to display the maximum value (highest value) of the ResponseSize field.

Command

... | timechart span=1h max(ResponseSize)

Output

Timestamp

Max
(Response
Size)
Jul 11 2013 3:00 PM200

Back to examples ↑

min with by parameter

In this example, you use the command to display the minimum value (smallest value) of the ResponseSize field, grouped by the ClientIp field. By running this command, you can understand the hosts from where minimum values are derived.

Command

... | timechart span=1hr min(ResponseSize) by ClientIp

Output

Timestamp

10.1.1.140:min
(Response
Size)

10.1.1.141:min
(Response
Size)

10.1.1.142:min
(Response
Size)

10.1.1.143:min
(Response
Size)

Jul 11 2013 3:00 PM100150200100
Jul 11 2013 4:00 PM0000

Back to examples ↑

min, max, avg, and stddev

In this example, you use the command to display the minimum (smallest), maximum (highest), and average of the ResponseSize field values.

Command

... | timechart span=1h min(ResponseSize), max(ResponseSize), avg(ResponseSize), 
stddev(ResponseSize)

Output

Timestamp

min(Response
Size)

max(Response
Size)

avg(Response
Size)

stddev(Response

Size)

Jul 11 2013 3:00 PM100200137.50041.458

Back to examples ↑

Notes

  • If the data contains an event with no time stamp, the product assigns a time stamp to that event at the time of indexing. The same time stamp is used for displaying the time bucket when you run this command.
  • You cannot run this command to display more than 100 buckets.

  • For plotting a line graph, ensure that the value of the span attribute is smaller than the time interval over which the search is run. Otherwise, the line graph is not plotted correctly. For example, if you are searching for the last 60 minutes, then the span value must be less than 60 minutes.

  • While using the sum and avg functions in your search syntax, the following conventions apply:
    • If the timechart command is the first command after the initial search query, the fields specified in the sum and avg functions must be of the field type INTEGER or LONG.
      The field type can be specified while creating a data pattern.
    • If the timechart command is preceded by another search command, the fields specified in the sum and avg functions must be numbers.

  • Fields with duplicate names can have conflicting field types when one field type is set to STRING, while the other is set to any of the numeric field types such as LONG or INTEGER. In this scenario, you can run the timechart command, however you might not be able to see accurate results unless you apply the workaround described in following example.

    Example

    If: You were running the following search string where ignored field is saved with the field type STRING and INTEGER:

    _index=metrics DATA_PATTERN=”ITDA Metrics” | timechart span=1d sum(ignored)

    Then: In your search string, include the filter search command command with isNumeric function before the timechart command, as follows:

    _index=metrics DATA_PATTERN=”ITDA Metrics” | filter isNumeric (ignored) | timechart span=1d sum(ignored)

Was this page helpful? Yes No Submitting... Thank you
Last modified by Priyanka Nanwani on Feb 27, 2017
search using reference search_commands examples

Comments

Log in or register to comment.

tail search command
top search command
© Copyright 2014-2017 BMC Software, Inc
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2023 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.