Welcome to the jqtop wiki!

https://github.com/shadyabhi/jqtop/blob/master/README.md#what-does-it-do

https://github.com/shadyabhi/jqtop/blob/master/README.md#short-tutorial

Usage: jqtop --file FILE [--interval INTERVAL] [--maxresult MAXRESULT] [--verbose] [--clearscreen] [--fields FIELDS] [--filters FILTERS]

Options:
  --file FILE            Path to file that will be read
  --interval INTERVAL, -i INTERVAL
                         Interval at which stats are calculated [default: 1]
  --maxresult MAXRESULT, -m MAXRESULT
                         Max results to show [default: 10]
  --verbose, -v
  --clearscreen, -c      Clear screen each time stats are shown
  --fields FIELDS        Fields that need to shown for stats
  --filters FILTERS      Filters to filter lines that'll be processed
  --help, -h

We will go through each option in detail.

This takes path to file that will be tailed. If this argument is nor present, the program reads from stdin.

Default is 1s. This is the interval at which stats are calculated. On a low qps server, you might want to see stats every 5s, you can use this option to change that behavior.

The reason this option exists is, if you choose a field which has too many variants, the CLI can spit a lot of into that you don't want. Typically, you would mostly be interested in only top few entries. The default is set to 10 for this one.

In case, you need verbose debugging messages, use this.

The batch mode is the default mode. In case, you don't care about historic values and only want to see latest values, you can this option to see only the latest stats. This is like, executing clear command in your shell after every output.

Fields are what show up as stats in the output.

A single field can be printed by using --fields status_code. To use multiple fields, we use a semi-colon separated list of strings. For eg, --fields 'status_code;uri'.

We have two types of fields:-

Fields that already exist in the doc.

Fields that are "derived" from already existing fields by doing some operations. For ex, you might have field like uri in your JSON and you want to extract domain out of it. For this, you can use a simple regex like //(.*?)/' to extract the domain` out of it.

To create a derived field, you use an intuitive expression like:- domain = regex_capture(uri, "//(.*?)/").

Functions supported:-

• regex_capture(uri, "//(.*?)/"): Returns the matched string based on regex //(.*?)/ on the string with value of uri field in JSON doc.

Filters are a way to filter lines that'll be processed by our program. As of today, we've 3 functions available to us:- https://github.com/shadyabhi/jqtop/blob/master/constants.go#L7

You can negate a function by prepending it with !. For eg, !contains(domain, "spammy.domain.com") will make sure that JSON docs which have value of field domain as spammy.domain.com won't be part of our stats.

Functions available as of today:-

• equals(field_name, "spammy.domain.com": This returns true if JSON document has a field field_name and it's value is "exactly" equal to spammy.domain.com.
• contains(field_name, "needle"): This returns true if needle string is contained in the value of field field_name.
• regex(field_name, "ignore.*"): This returns true if regex ignore.* finds a match in the string field_name.

So, a complex filter that uses multiple functions could look like:- (as expected, semi-colon separated list)

!contains(status_code, "200"); regex(uri, "www.*");

Means, this filter ensures that we process only lines that have status_code != 200 and the uri field matches the regex www.*. Basically, we're trying to look for non-200 status codes for all domains starting with www.