Splunk® Enterprise

Search Reference

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

tstats

The tstats command is an internal command used to calculate statistics over tsidx files created with the tscollect command. Currently, it is an experimental command and not supported by Splunk.

When you want to report on very large data sets, use the tscollect command to save search results into a tsidx file that exists in a specific namespace (that you create with the tscollect command).

Then use the tstats command to calculate statistics on the data summarized into the tsidx file. Because you are not reading events from raw data, you can expect significantly faster search and reporting performance. tstats operates in a manner similar to that of stats; the primary differences are that:

  • it is a generating processor, so it must be the first command in a search
  • it uses a smaller set of stats functions
  • it requires you to specify the namespace for the target tsidx file or the job id of the tscollect job

Since tstats does not support all the functionality of the normal stats command, you have the option to output results in the prestats format for use by stats, which combines the speed of tstats with all the functionality of stats. Operating in prestats mode also enables preview for results, so this is highly recommended for large data sets.

Note: Except in prestats and append modes (prestats=t and append=t), this is command is a generating processor, so it must be the first command in a search. See the Syntax below for more details.

Synopsis

Performs statistical queries on tsidx files created using tscollect.

Syntax

| tstats [append=<bool>] [prestats=<bool>] <aggregate-opt>... FROM <namespace|tscollect-job-id> [WHERE <search_query>] [GROUPBY <field-list> [span=<timespan>] ]

Required arguments

aggregate-opt
Syntax: count|count(<field>)|sum(<field>)|sumsq(<field>)|distinct(<field>)|avg(<field>)|stdev(<field>)|<stats-fn>(<field>) [AS <string>]
Description: Either perform a basic count, get the values of a field, or perform a function. You can also rename the result using 'AS'. While there are only a few directly supported functions in tstats, if you are running with the prestats option (and only then) you can supply any function that stats supports with <stats-fn>.
namespace
Syntax: <string>
Description: Define a location for the tsidx file with $SPLUNK_DB/tsidxstats. This namespace location is also configurable in index.conf, with the attribute tsidxStatsHomePath.
tscollect-job-id
Syntax: <string>
Description: The job ID of a tscollect search.

Optional arguments

append
Syntax: append=<bool>
Description: When in prestats mode (prestats=t), enables append=t where the prestats results append to any input results.
prestats
Syntax: prestats=<bool>
Description: Use this to perform any stats function that tstats does not support (is not listed as an aggregate option). When true, this option also enables preview for results. For more information see Functions for stats, chart, and timechart. Defaults to false.
<field-list>
Syntax: <field>, <field>, ...
Description: Specify a list of fields to group results.


Filtering with where

You can provide any number of aggregates (aggregate-opt) to perform, and also have the option of providing a filtering query using the WHERE keyword. This query looks like a normal query you would use in the search processor.

Grouping by _time

You can provide any number of GROUPBY fields. If you are grouping by _time, you should supply a timespan for grouping the time buckets. This timespan looks like any normal timespan in Splunk, span='1hr' or '3d'.

Examples

Example 1: Gets the count of all events in the mydata namespace.

| tstats count FROM mydata

Example 2: Returns the average of the field foo in mydata, specifically where bar is value2 and the value of baz is greater than 5.

| tstats avg(foo) FROM mydata WHERE bar=value2 baz>5

Example 3: Gives the count split by each day for all the data in mydata

| tstats count from mydata GROUPBY _time span=1d

Example 4: Uses prestats mode to calculate the median of the field foo.

| tstats prestats=t median(foo) FROM mydata | stats median(foo)

Example 5: Use prestats mode in conjunction with append to compute the median values of foo and bar, which are in different namespaces.

| tstats prestats=t median(foo) from mydata | tstats prestats=t append=t median(bar) from my otherdata | stats median(foo) median(bar)

See also

stats, tscollect

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the tstats command.

PREVIOUS
tscollect
  NEXT
About searches in the CLI

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters