CLI Traffic Queries
Currently two top level traffic queries are available in the CLI, show traffic and show traffic-current. They share a number of syntax clauses that can be used to examine current and historical flow samples captured by Director. This page details the specifics of the syntax for each clause that can be used in a traffic query.
In general, clauses do not need to be strictly ordered but can be used in whatever order makes sense to you. However, individual clauses expect specific syntax and should alert you if you violate their rules.
Director CLI traffic reporting operates on recorded packet samples, which are written every 30 seconds in addition to being sampled to begin with, so query results (particularly show traffic-current) should be evaluated with this in mind. This does not affect Director triggers, which activate based on live up-to-the-second rate calculations.
Organizational Clauses
These clauses modify which organizational units are queried, and how the queries are structured among those units. In general, they align with the various mapping configurations used to align workflows with groups and/or zones, so you can easily query workflows in whole or by parts. You can also directly look for data on a specific host.
For
The for clause limits the query to the defined organizational element. This clause defaults to all in order to look up all traffic data available. When entering group, group-recursive, or zone IDs, you can query multiple IDs at once as long as they are comma separated (trailing commas are allowed). These clauses are largely identical to those found in the mapping configuration, though you can additionally look for data on a specific host or directly use a workflow's configured set of groups/zones.
Default: all
Used by: show traffic, show traffic-current
# show traffic for
all: All traffic (default)
group: Traffic for Group IDs
group-recursive: Traffic for Group (and subgroup) IDs
zone: Traffic for Zone IDs
workflow: Traffic for workflow name
host: Traffic for host
By
The by clause modifies the final display of the query to group results by the requested organizational element. This clause defaults to total, which implicitly groups data against the unit defined in the for clause. This clause cannot be more specific than the unit requested in the for clause (e.g. showing by group doesn't make sense when you requested for zone).
Default: total
Used by: show traffic, show traffic-current
# show traffic by
total: One row with the total (default)
group: One row for each group
zone: One row for each zone
host: One row for each host
Per
The per clause modifies the query to calculate the requested metric against the unit in this clause. This clause defaults to row, which implicitly calculates data against the unit defined in the by clause. This clause cannot be more specific than the unit requested in the by clause. This is generally useful when you are trying to determine per-zone or per-host triggers from within a larger organizational unit.
Default: row
Used by: show traffic
# show traffic per
row: Calculate per-row rates
zone: Calculate per-zone rates
host: Calculate per-host rates
Organizational Examples
To illustrate how these clause modify queries, let's look at the maximum observed bit rate for a zone:
# show traffic for zone 52
Querying max(bits_incoming) for zone 52 by total calculated per row
Rows processed: 100.0% [====================================================================>] 9454190/9454190 eta [00:00]
Top 10 results:
Max(bits_incoming)
40.1 Mbps
This shows the maximum incoming bit rate observed for the zone itself, but what if we wanted to check it per host?
# show traffic for zone 52 per host
Querying max(bits_incoming) for zone 52 by total calculated per host
Rows processed: 100.0% [====================================================================>] 9454190/9454190 eta [00:00]
Top 10 results:
Max(bits_incoming)
25.4 Mbps
This shows us the peak observed incoming bit rate for a single host in that zone in the past week, but let's actually show some details using by host so we can check our other internal network reporting:
The following is artifically generated test traffic, not real hosts.
# show traffic for zone 52 by host per host
Querying max(bits_incoming) for zone 52 by host calculated per host
Rows processed: 100.0% [====================================================================>] 9462414/9462414 eta [00:00]
Top 10 results:
Host | Max(bits_incoming)
132.155.234.37 | 25.4 Mbps
132.155.234.159 | 9.9 Mbps
132.155.211.227 | 3.9 Mbps
132.155.203.55 | 2.4 Mbps
132.155.209.6 | 973.7 kbps
132.155.242.162 | 795.9 kbps
132.155.196.169 | 791.5 kbps
132.155.243.145 | 686.3 kbps
132.155.196.198 | 588.3 kbps
132.155.235.143 | 529.5 kbps
Note that since the per clause defaults to the unit of the by clause, you also could have simply done:
# show traffic for zone 52 by host
Querying max(bits_incoming) for zone 52 by host calculated per row
Rows processed: 100.0% [====================================================================>] 9470458/9470458 eta [00:00]
Top 10 results:
Host | Max(bits_incoming)
132.155.234.37 | 25.4 Mbps
132.155.234.159 | 9.9 Mbps
132.155.211.227 | 3.9 Mbps
132.155.203.55 | 2.4 Mbps
132.155.209.6 | 973.7 kbps
132.155.242.162 | 795.9 kbps
132.155.196.169 | 791.5 kbps
132.155.243.145 | 686.3 kbps
132.155.196.198 | 588.3 kbps
132.155.235.143 | 529.5 kbps
You may have noticed that all of these results are limited to the top 10, even if there's only one result. This is a gentle reminder that there is a default value of 10 for the top clause.
Time Clauses
By default, Director stores up to a week's worth of data. Unless otherwise directed, show traffic queries will work across that entire span of time (or if Director has been up for less than a week, across whatever data is available) and show traffic-current queries will look for the latest available data. Time clauses can be used to modify queries to look at either a different time range for show traffic or a different point in time for show traffic-current.
From
The from clause modifies the query to only use data after this point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). If not specified this uses the oldest data available.
Default: Oldest timestamp available (up to 1 week ago)
Used by: show traffic
# show traffic from
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago
To
The to clause modifies the query to only use data before this point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). If not specified this uses the newest data available.
Default: Now
Used by: show traffic
# show traffic to
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago
At
The at clause modifies the query to retrieve traffic conditions at a specific point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). If not specified this uses the newest data available (e.g. traffic as of right now).
Default: Now
Used by: show traffic-current
# show traffic-current at
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago
Metric Clauses
Director stores flow sample data across multiple metric dimensions. Broadly speaking, these dimensions map to:
- Type of Traffic: The type of traffic, such as TCP or fragmented packets.
- Traffic Unit: Either bit or packet rate values.
- Direction of Traffic: Traffic either coming into your network or leaving it.
The combination of all three of these dimensions are stored as metrics that can be queried independently for each possible combination of values (the query display will show which column it ends up using). Without modification, queries will look for bits_incoming by default, which give you the all type of traffic in bits per second, coming into your network.
Depending on the query type, it is further performing an aggregation on this metric to show relevant data as a measure of that metric.
The help commands for all metrics are shown at the top level (i.e. you'll see them by entering show traffic ? or show traffic-current ?).
Type
Director tracks a number of different traffic types. By default queries will examine all traffic, but it can be filtered down to a specific type:
Default: all
Used by: show traffic, show traffic-current
all: All traffic types
tcp: TCP Traffic
tcp-syn: TCP-Syn Traffic
udp: UDP Traffic
icmp: ICMP Traffic
fragmented: Fragmented Traffic
Unit
Director tracks data in both bit and packet rates per second:
Default: bits
Used by: show traffic, show traffic-current
bits: in bits per second (bps)
packets: in packets per second (pps)
Direction
Director tracks samples to see if if they are inbound to destinations in your network (as defined in rWeb, provided they are not the default prefixes, or traffic sent by them:
Default: incoming
Used by: show traffic, show traffic-current
incoming: Inbound traffic
outgoing: Outbound traffic
Measure
All queries perform some sort of aggregation on received samples. show traffic allows a variety of statistical measures, while show traffic-current always implicitly performs a sum operation to give you the total of the requested measure at a point in time. From the CLI, therefore, you can only modify show traffic queries to change which aggregation you are performing:
Default: peak
Used by: show traffic
peak: Peak rate
average: Average rate
95pct: 95th percentile rate
The aggregation calculations are all performed against recorded data. It's important to note that: a) This traffic is sampled to begin with, and b) The data is recorded in 30 second intervals. As a result, this means that average and 95pct calculations on a per host basis are going to be heavily biased by the consistency of the sampling (per zone will probably be more correct, and it would be better still to scope the query for a specific Zone). Similarly, peak calculations could miss reporting traffic spikes that occur between 30 second intervals (though the live trigger will likely react to the spike).
Measure Examples
The metric clauses can be combined with the organizational clauses to drill down into observed traffic patterns. For example, if we wanted to know the average per host UDP packet rate for a zone:
# show traffic average udp packets for zone 130 per host
Querying avg(udp_packets_incoming) for zone 130 by total calculated per host
Rows processed: 100.0% [======================================================================>] 118701/118701 eta [00:00]
Top 10 results:
Avg(udp_packets_incoming)
671.1 pps
And briefly see how we compare to that average currently:
# show traffic-current udp packets by host for zone 130
Querying Current udp_packets_incoming for zone 130 by host
Rows processed: 100.0% [========================================================================>] 63933/63933 eta [00:00]
Top 10 results:
Host | Sum(udp_packets_incoming)
140.34.129.15 | 1.3 kpps
140.34.129.135 | 0.0 pps
140.34.140.152 | 0.0 pps
We could also check the 95th percentile as a sanity check against any current per-host trigger levels:
# show traffic 95pct udp packets for zone 130 per host
Querying quantileExact(.95)(udp_packets_incoming) for zone 130 by total calculated per host
Rows processed: 100.0% [======================================================================>] 131891/131891 eta [00:00]
Top 10 results:
Quantileexact(.95)(udp_packets_incoming)
3.2 kpps
As a final illustration, we can also do things like check which zones had the most outgoing ICMP traffic:
# show traffic icmp outgoing by zone
Querying max(icmp_bits_outgoing) for all by zone calculated per row
Rows processed: 100.0% [==================================================================>] 88594062/88594062 eta [00:00]
Top 10 results:
Zone | Max(icmp_bits_outgoing)
80 | 285.3 kbps
81 | 158.9 kbps
50 | 82.4 kbps
52 | 52.6 kbps
49 | 29.0 kbps
51 | 26.5 kbps
82 | 21.7 kbps
83 | 14.0 kbps
181 | 8.1 kbps
55 | 0.0 bps
Top
By default all traffic queries are limited to the top 10 results (in descending order by the metric queried). In most cases this is a reasonable default but when working with larger sets of results you may want to see more results or not limit it at all. If using top all, the final query result will not render a "Top <n> results:" line when printing output.
Default: 10
Used by: show traffic, show traffic-current
# show traffic top
all: All rows
<n>: Top <n> rows