• Spaces
  • Collections
  • Help
    • ×
     
     
    •  
    BMC TrueSight IT Data Analytics 2.0

    Page tree

    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

    Searching the data

    Syntax

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

    timechart span=<duration><timescale> <aggregate-function>+ [by <field>]

    In the preceding syntax, the following definitions apply:

    • + indicates one or more similar expressions separated by a comma (,) or space.
    • [expression] indicatesit 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
      Minutes
      m | min | mins | minute | minutes
      Hours
      h | hr | hrs | hour | hours
      Days
      d | 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:

      FunctionSyntaxDescription
      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
    • 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.

    Note: 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.

    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.

    ... | timechart span=1hr count(RequestType) 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.
    • 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.

    Best practices

    While performing statistical operations like sum, average, and standard deviation, the field on which you are performing these operations must be numeric. This means at the time of creating the data pattern and defining fields, you must have assigned the field type as LONG or INTEGER. For more information, see Creating data patterns manually.

    If you run these statistical operations on a non-numeric field (with the field type STRING), then you will not see any results. To see results, you must edit the data pattern and change the field type to LONG or INTEGER. As a workaround, you can also edit the syntax of your original search string, to use another command after the search query and before the timechart command, as described in the following example.

    Example

    If: You were running the following search string where ignored field is saved with the field type STRING and you could not see expected results:

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

    Then: In your search string, include another command before the stats command, as follows:

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

    © Copyright 2005-2024 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.