chart

chart

Synopsis

Returns results in a tabular output for charting.

Syntax

chart [sep=<string>] [cont=<bool>] [limit=<int>] [agg=<stats-agg-term>] ( <stats-agg-term> | <sparkline-agg-term> | <eval-expression>...) [ by <field> (<bucketing-option> )... [<split-by-clause>] ] | [ over <field> (<bucketing-option>)... (by <split-by-clause>] ]

For a list of chart functions with descriptions and examples, see "Functions for stats, chart, and timechart".

Required arguments

<stats-agg-term>

Syntax: <stats-agg-term>

Description: For a list of stats functions with descriptions and examples, see "Functions for stats, chart, and timechart".

sparkline-agg-term

Syntax: <sparkline-agg> [AS <wc-field>]

Description: A sparkline specifier optionall renamed to a new field.

eval-expression

Syntax: <eval-math-exp> | <eval-concat-exp> | <eval-compare-exp> | <eval-bool-exp> | <eval-function-call>

Description: A combination of literals, fields, operators, and functions that represent the value of your destination field. For more information, see the Functions for eval. For these evaluations to work, your values need to be valid for the type of operation. For example, with the exception of addition, arithmetic operations may not produce valid results if the values are not numerical. Additionally, Splunk can concatenate the two operands if they are both strings. When concatenating values with '.', Splunk treats both values as strings regardless of their actual type.

Optional arguments

agg

Syntax: <stats-agg-term>

Description: For a list of stats functions with descriptions and examples, see "Functions for stats, chart, and timechart".

bucketing-option

Syntax: bins | span | <start-end>

Description: Discretization options. If a bucketing option is not supplied, timechart defaults to bins=300. This finds the smallest bucket size that results in no more than 300 distinct buckets. For more bucketing options, see the bucket command reference.

cont

Syntax: <bool>

Description: Specifies whether its continuous or not.

limit

Syntax: <int>

Description: Specify a limit for series filtering; limit=0 means no filtering.

single-agg

Syntax: count|<stats-func>(<field>)

Description: A single aggregation applied to a single field (can be evaled field). No wildcards are allowed. The field must be specified, except when using the special count aggregator that applies to events as a whole.

sep

Syntax: sep=<string>

Description: Used to construct output field names when multiple data series are used in conjunctions with a split-by field.

split-by-clause

Syntax: <field> (<tc-option>)* [<where-clause>]

Description: Specifies a field to split by. If field is numerical, default discretization is applied; discretization is defined with tc-option.

Sparkline function options

Sparklines are inline charts that appear within table cells in search results and display time-based trends associated with the primary key of each row. Read more about how to "Add sparklines to your search results" in the User Manual.

sparkline-agg

Syntax: sparkline (count(<wc-field>), <span-length>) | sparkline (<sparkline-func>(<wc-field>), <span-length>)

Description: A sparkline specifier, which takes the first argument of a aggregation function on a field and an optional timespan specifier. If no timespan specifier is used, an appropriate timespan is chosen based on the time range of the search. If the sparkline is not scoped to a field, only the count aggregator is permitted.

sparkline-func

Syntax: c() | count() | dc() | mean() | avg() | stdev() | stdevp() | var() | varp() | sum() | sumsq() | min() | max() | range()

Description: Aggregation function to use to generate sparkline values. Each sparkline value is produced by applying this aggregation to the events that fall into each particular time bucket.

Bucketing options

bins

Syntax: bins=<int>

Description: Sets the maximum number of bins to discretize into.

span

Syntax: span=<log-span> | span=<span-length>

Description: Sets the size of each bucket, using a span length based on time or log-based span.

<start-end>

Syntax: end=<num> | start=<num>

Description:Sets the minimum and maximum extents for numerical buckets. Data outside of the [start, end] range is discarded.

Log span syntax

<log-span>

Syntax: [<num>]log[<num>]

Description: Sets to log-based span. The first number is a coefficient. The second number is the base. If the first number is supplied, it must be a real number >= 1.0 and < base. Base, if supplied, must be real number > 1.0 (strictly greater than 1).

Span length syntax

span-length

Syntax: [<timescale>]

Description: A span length based on time.

<span>

Syntax: <int>

Description: The span of each bin. If using a timescale, this is used as a time range. If not, this is an absolute bucket "length."

<timescale>

Syntax: <sec> | <min> | <hr> | <day> | <month> | <subseconds>

Description: Time scale units.

<sec>

Syntax: s | sec | secs | second | seconds

Description: Time scale in seconds.

<min>

Syntax: m | min | mins | minute | minutes

Description: Time scale in minutes.

<hr>

Syntax: h | hr | hrs | hour | hours

Description: Time scale in hours.

<day>

Syntax: d | day | days

Description: Time scale in days.

<month>

Syntax: mon | month | months

Description: Time scale in months.

<subseconds>

Syntax: us | ms | cs | ds

Description: Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds).

tc options

tc-option

Syntax: <bucketing-option> | usenull=<bool> | useother=<bool> | nullstr=<string> | otherstr=<string>

Description: Options for controlling the behavior of splitting by a field.

usenull

Syntax: usenull=<bool>

Description: Controls whether or not a series is created for events that do not contain the split-by field.

nullstr

Syntax: nullstr=<string>

Description: If usenull is true, this series is labeled by the value of the nullstr option, and defaults to NULL.

useother

Syntax: useother=<bool>

Description: Specifies if a series should be added for data series not included in the graph because they did not meet the criteria of the <where-clause>.

otherstr

String: otherstr=<string>

Description: If useother is true, this series is labeled by the value of the otherstr option, and defaults to OTHER.

where clause

where clause

Syntax: <single-agg> <where-comp>

Description: Specifies the criteria for including particular data series when a field is given in the tc-by-clause. The most common use of this option is to select for spikes rather than overall mass of distribution in series selection. The default value finds the top ten series by area under the curve. Alternately one could replace sum with max to find the series with the ten highest spikes.This has no relation to the where command.

<where-comp>

Syntax: <wherein-comp> | <wherethresh-comp>

Description: A criteria for the where clause.

<wherein-comp>

Syntax: (in|notin) (top|bottom)<int>

Description: A where-clause criteria that requires the aggregated series value be in or not in some top or bottom grouping.

<wherethresh-comp>

Syntax: (<|>)( )?<num>

Description: A where-clause criteria that requires the aggregated series value be greater than or less than some numeric threshold.

Description

Create tabular data output suitable for charting. The x-axis variable is specified with a by field and is discretized if necessary. Charted fields are converted to numerical quantities if necessary.

Whereas timechart generates a chart with _time as the x-axis, chart produces a table with an arbitrary field as the x-axis. In addition, chart allows for a split-by field. When such a field is included, the output will be a table where each column represents a distinct value of the split-by field.

This is in contrast with stats, where each row represents a single unique combination of values of the group-by fields. The number of columns to be included is by default limited to 10, but can be adjusted by the inclusion of an optional where clause. See where-clause for a more detailed description.

Chart allows for an eval-expression, which is required to be renamed unless a split-by clause is present. You can also specify the the x-axis field after the over keyword, before any by and subsequent split-by clause. The limit and agg options allow easier specification of series filtering. The limit=0 means no series filtering. The limit and agg options are ignored if an explicit where clause is provided.

A note about split-by fields

If you use chart or timechart, you cannot use a field that you specify in a function as your split-by field as well. For example, you will not be able to run:

However, you can work around this with an eval expression, for example:

Examples

Example 1

This example uses the sample dataset from the tutorial but should work with any format of Apache Web access log. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

Chart the number of different page requests, GET and POST, that occurred for each Web server.

This example uses eval expressions to specify the different field values for the stats command to count. The first clause uses the count() function to count the Web access events that contain the method field value GET. Then, it renames the field that represents these results to "GET" (this is what the "AS" is doing). The second clause does the same for POST events. The counts of both types of events are then separated by the Web server, indicated by the host field, from which they appeared.

This returns the following table:

Click Show report to format the chart in Report Builder. Here, the y-axis is shown on a logarithmic scale:

This chart displays the total count of events for each event type, GET or POST, based on the host value. The logarithmic scale is used for the y-axis because of the difference in range of vales between the number of GET and POST events.

Note: You can use the stats, chart, and timechart commands to perform the same statistical calculations on your data. The stats command returns a table of results. The chart command returns the same table of results, but you can use the Report Builder to format this table as a chart. If you want to chart your results over a time range, use the timechart command. You can also see variations of this example with the chart and timechart commands.

Example 2

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, All time.

Create a chart to show the number of transactions based on their duration (in seconds).

This search uses the transaction command to define a transaction as events that share the clientip field and fit within a ten minute time span. The transaction command creates a new field called duration, which is the difference between the timestamps for the first and last events in the transaction. (Because maxspan=10s, the duration value should not be greater than this.)

The transactions are then piped into the chart command. The count() function is used to count the number of transactions and separate the count by the duration of each transaction. Because the duration is in seconds and you expect there to be many values, the search uses the span argument to bucket the duration into bins of log2 (span=log2). This produces the following table:

Click Show report to format the chart in Report Builder. Here, it's formatted as a column chart:

As you would expect, most transactions take between 0 and 2 seconds to complete. Here, it looks like the next greater number of transactions spanned between 256 and 512 seconds (approximately, 4-8 minutes). (In this case however, the numbers may be a bit extreme because of the way that the data was generated.)

Example 3

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, All time.

Create a chart to show the average number of events in a transaction based on the duration of the transaction.

This example uses the same transaction defined in Example 2. The transaction command also creates a new field called eventcount, which is the number of events in a single transaction.

The transactions are then piped into the chart command and the avg() function is used to calculate the average number of events for each duration. Because the duration is in seconds and you expect there to be many values, the search uses the span argument to bucket the duration into bins of log2 (span=log2). This produces the following table:

Click Show report to format the chart in Report Builder. Here, it's formatted as a pie chart:

Each wedge of the pie chart represents the average number of events in the transactions of the corresponding duration. After you create the pie chart, you can mouseover each of the sections to see these values (in Splunk Web).

Example 4

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

Chart how many different people bought something and what they bought at the Flower & Gift shop Yesterday.

This search takes the purchase events and pipes it into the chart command. The dc() or distinct_count() function is used to count the number of unique visitors (characterized by the clientip field). This number is then charted over each hour of the day and broken out based on the category_id of the purchase. Also, because these are numeric values, the search uses the usenull=f argument to exclude fields that don't have a value.

This produces the following table:

Click Show report to format the chart in Report Builder. Here, it's formatted as a line chart:

Each line represents a different type of product that is sold at the Flower & Gift shop. The height of each line shows the number of different people who bought the product during that hour. In general, it looks like the most popular items at the online shop were flowers. Most of the purchases were made early in the day, around lunch time, and early in the evening.

Example 5

This example uses recent (September 29-October 6, 2010) earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that contains the source network (Src), ID (Eqid), version, date, location, magnitude, depth (km) and number of reporting stations (NST) for each earthquake over the last 7 days. Download the text file, M 1+ earthquakes, past 7 days, and upload it to Splunk. Splunk should extract the fields automatically.

Create a chart that shows the number of earthquakes and the magnitude of each one that occurred in and around California.

This search counts the number of earthquakes that occurred in the the California regions. The count is then broken down for each region based on the magnitude of the quake. Because the Region value is non-numeric, the search uses the useother=f argument to exclude events that don't match.

This produces the following table:

Click Show report to format the chart in Report Builder. Here, it's formatted as a scatter chart:

This chart shows that the majority of the quakes that occurred in the past week were of magnitudes between 1 and 2.2. Quakes of higher magnitude were less frequent--Yay!

Also, the plot points for each region may overlap with another region's plot. If you want to see just the points for one region at a time, mouseover the region in the legend. If you want to see metrics for an individual point, mouseover that point on the chart. A tooltip will open and display the corresponding Magnitude, Region, and count of earthquakes.

More examples

Example 1: Return max(delay) for each value of foo.

Example 2: Return max(delay) for each value of foo split by the value of bar.

Example 3: Return the ratio of the average (mean) "size" to the maximum "delay" for each distinct "host" and "user" pair.

Example 4: Return the the maximum "delay" by "size", where "size" is broken down into a maximum of 10 equal sized buckets.

Example 5: Return the average (mean) "size" for each distinct "host".

See also

timechart, bucket, sichart

Answers

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

• Was this topic useful?
• Post a comment