Documentation
¶
Overview ¶
Package stats exposes tshark's -z statistics as panels pcaptui can show.
tshark carries a large collection of analyses behind -z; pcaptui used only conv,* for the conversations view and follow,* for stream reassembly. The ones here answer the questions asked most often of a capture: what is in it, what is wrong with it, who is on the wire, and how its HTTP and DNS turned out.
Index ¶
- Variables
- func DNSFilter(parent string, name string) string
- func HTTPFilter(name string) string
- func IOStatArg(seconds float64, displayFilter string) string
- func IOStatInterval(seconds float64) int
- func MakeCommands() commands
- type CredentialRow
- type EndpointRow
- type ExpertRow
- type HierarchyRow
- type ILoaderCmds
- type IOStatRow
- type IStatsCallbacks
- type Loader
- type SeverityTotal
- type Stat
- type TreeRow
Constants ¶
This section is empty.
Variables ¶
var ( // Expert is tshark's expert information: the warnings the dissectors // raise - retransmissions, malformed packets, protocol violations. // Wireshark shows it under Analyze > Expert Information. Expert = Stat{ Name: "Expert Information", Command: "expert", Key: 'e', Summary: "Problems the dissectors found in this capture", // contains filtered or unexported fields } // ProtoHierarchy is the protocol hierarchy: every protocol present, by // packet and byte count. Wireshark shows it under Statistics > Protocol // Hierarchy. ProtoHierarchy = Stat{ Name: "Protocol Hierarchy", Command: "hierarchy", Key: 'y', Summary: "Every protocol in this capture, by packets and bytes", // contains filtered or unexported fields } // Endpoints is who is on the wire and how much each of them sent and // received. Wireshark shows it under Statistics > Endpoints. // // Addresses rather than every endpoint type: an address is the thing // people look for by name, and it is the one a display filter can be built // from without knowing which layer to ask about. // // Both families, in one pass. Asking only for IPv4 meant a capture of IPv6 // traffic answered "Nothing to report" to the question "who is on the // wire" while the protocol hierarchy in the same dialog listed ipv6 six // lines above. Measured on a 22 MB capture: adding the second table cost // nothing outside the noise between runs. Endpoints = Stat{ Name: "Endpoints", Command: "endpoints", Key: 't', Summary: "Who is on the wire, by packets and bytes", // contains filtered or unexported fields } // HTTP counts the responses by status: how many succeeded, how many were // not found, how many the server failed on. Wireshark shows it under // Statistics > HTTP > Packet Counter. // // Key `w` for web: `h` is taken by the vim-style movement keys. HTTP = Stat{ Name: "HTTP", Command: "http", Key: 'w', Summary: "How the HTTP responses in this capture turned out", // contains filtered or unexported fields } // DNS is what was asked for and how the answers turned out: how many // lookups failed, with which code, and how long the server took. // Wireshark shows it under Statistics > DNS. DNS = Stat{ Name: "DNS", Command: "dns", Key: 'd', Summary: "What was asked of DNS and how the answers turned out", // contains filtered or unexported fields } // Credentials is the logins tshark could read in the clear: HTTP basic // auth, FTP, POP, IMAP, SMTP and telnet. Wireshark shows it under // Tools > Credentials. // // The one statistic here that names a packet rather than counting // occurrences, so its rows filter exactly: `frame.number == 1`. // // It ignores a display filter, measured rather than assumed - see // ignoresFilter - so it is never given one. // // Key `a` for auth: `c` is taken by copy-mode. Credentials = Stat{ Name: "Credentials", Command: "credentials", Key: 'a', Summary: "Logins this capture carries in the clear", // contains filtered or unexported fields } // Overview is the three of them at once: what is in the capture, what is // wrong with it, and who is on the wire. // // It is the question somebody actually has when handed a capture, and // answering it needed knowing three commands. tshark accepts several -z // arguments in one invocation, so this is one pass over the file rather // than three. Overview = Stat{ Name: "Overview", Command: "overview", Key: 'o', Summary: "What is in this capture, what is wrong with it, who is on the wire", // contains filtered or unexported fields } )
var All = []Stat{Overview, Expert, ProtoHierarchy, Endpoints, Credentials, HTTP, DNS}
All is every statistic pcaptui offers, in the order they are presented.
var Goroutinewg *sync.WaitGroup
Functions ¶
func DNSFilter ¶ added in v1.1.0
DNSFilter is the display filter that shows the packets a row counted, or "" when there is no honest one.
A row's name means nothing on its own here: "A" under Query Type is what was asked for and "A" under Answer Type is what came back, and half the table is headings like "Label Stats" that count nothing a filter could select. So the section the row sits in decides, and only four sections offer one:
Total Packets every DNS packet Response the query/response split rcode how the responses turned out Query Type what was asked for
The rest are shown and not offered. They are averages and lengths - "Qname Len", "no. of answers" - and no display filter selects "the packets that contributed to this average".
One of the four does not agree with its own count, and cannot be made to. tshark counts the rcode bits of every DNS header, and a query carries a zero there, so a capture of two lookups reports "No error" three times: both queries and the one good answer. The dissector puts dns.flags.rcode on responses only, so the filter finds one packet where the row says three. The filter is still the useful half - "show me the answers that failed" is the question being asked - so it is offered, and the difference is Wireshark counting something no filter can name.
func HTTPFilter ¶ added in v1.1.0
HTTPFilter is the display filter that shows the packets a row counted, or "" when there is no honest one.
The rows are tshark's, and their names are the whole of what it says about them, so the filter is derived from the name. Only the rows whose meaning is unambiguous get one; "Other HTTP Packets" is tshark's own catch-all and no filter expresses it, so that row is shown and not offered.
func IOStatArg ¶ added in v1.2.0
IOStatArg is the -z argument for a capture of the given length in seconds.
The interval is chosen so that the answer is a shape rather than a list: too long and a burst is averaged away, too short and an hour of traffic arrives as thousands of rows. About twenty buckets reads well on one line, rounded up to a duration a person would have chosen - 1, 2, 5, 10 seconds, and so on - because "every 7 seconds" is harder to hold in the head than "every 10".
Seconds, because that is tshark's unit here. A capture shorter than the smallest interval gets one bucket, which is the truthful answer for it.
func IOStatInterval ¶ added in v1.2.0
IOStatInterval is the bucket size in seconds.
func MakeCommands ¶
func MakeCommands() commands
Types ¶
type CredentialRow ¶ added in v1.2.0
type CredentialRow struct {
Packet int
Protocol string // "HTTP basic auth", "FTP", "POP", "IMAP", "SMTP", telnet
Username string
Info string
}
CredentialRow is one login `tshark -z credentials` found in the clear.
Unlike every other statistic here, this one names the packet. The expert tap reports how often something happened and never where, so its rows have to be turned back into a display filter on their own text; a credential arrives with a frame number, so its filter is exact.
func ParseCredentials ¶ added in v1.2.0
func ParseCredentials(out string) []CredentialRow
ParseCredentials reads the output of `tshark -z credentials`:
Packet Protocol Username Info ------ -------- -------- -------- 1 HTTP basic auth user
By column position, taken off the header, because the protocol is several words - "HTTP basic auth" - and the username is whatever the user chose, which can be several words too. Splitting on whitespace would put half of a protocol into the username column.
func (CredentialRow) DisplayFilter ¶ added in v1.2.0
func (r CredentialRow) DisplayFilter() string
DisplayFilter is the packet this was found in.
type EndpointRow ¶ added in v1.1.0
type EndpointRow struct {
Address string
Packets int
Bytes int
TxPkts int
TxBytes int
RxPkts int
RxBytes int
}
EndpointRow is one address in `tshark -z endpoints,ip`.
Tx and Rx are kept apart from the totals because that is the question the table is usually asked: not how much an address moved, but which direction it moved it in. A host that received four megabytes and sent two hundred bytes is doing something different from one that did the reverse.
func ParseEndpoints ¶ added in v1.1.0
func ParseEndpoints(out string) []EndpointRow
ParseEndpoints reads the output of `tshark -z endpoints,ip`.
The layout is a rule, a title, the filter in force, a header of pipe-wrapped column names, then one line per address:
192.168.0.2 92 7748 bytes 48 3465 bytes 44 4283 bytes
The word "bytes" follows three of the six numbers, so the fields are read by dropping it and taking what is left: an address and six counts. Reading by column position would not survive an IPv6 address, which is wider than the column tshark lays out for it.
func (EndpointRow) DisplayFilter ¶ added in v1.1.0
func (r EndpointRow) DisplayFilter() string
DisplayFilter narrows the packet list to the traffic this address is part of, in either direction.
Which field depends on the address: Wireshark has no one name covering both, so `ip.addr` selects nothing for an IPv6 host and tshark rejects the filter outright. An IPv6 address is the one with a colon in it.
type ExpertRow ¶ added in v1.1.0
type ExpertRow struct {
Severity string // Errors, Warns, Notes, Chats
Count int
Group string // Sequence, Protocol, Malformed, Checksum, ...
Protocol string
Summary string
// Merged is how many of tshark's numbered rows this one stands for, and
// FirstNum/LastNum are the lowest and highest of those numbers. Zero for
// a row that arrived as itself. See CollapseNumbered.
Merged int
FirstNum int
LastNum int
}
ExpertRow is one line of `tshark -z expert`.
The severity is the section the row appeared under, not a column of its own: tshark prints "Errors (6)", a rule, a header and then the rows, and repeats that for warnings, notes and chats. Reading a row without its section loses the only thing that says how much it matters.
func CollapseNumbered ¶ added in v1.1.0
CollapseNumbered folds the rows tshark numbers into one row each.
Wireshark reports some expert items once per occurrence with a counter in the text - "Duplicate ACK (#1)", "Duplicate ACK (#2)" - and the tap reports each of those as a separate kind of problem. Measured on a capture of 376,832 packets: `tshark -z expert` printed 4,108 data rows, of which 4,095 were duplicate ACKs. Thirteen facts, arriving as four thousand lines, with the four that matter at the top and no way to see that from the summary, which said "and 4104 more".
The rows are merged in place: the first of a family keeps its position, so the order tshark chose - worst first - survives.
The count is the sum, and it is the right number: on that same capture the merged row said 143,325 and the filter it offers found exactly 143,325 packets.
func ParseExpert ¶ added in v1.1.0
ParseExpert reads the output of `tshark -z expert`.
Where the Summary column starts is read off the header line rather than assumed, because the summary is free text - it contains spaces, brackets and backslashes - so it can only be found by position, and the position differs between Wireshark releases.
func (ExpertRow) DisplayFilter ¶ added in v1.1.0
DisplayFilter is an expression matching the packets this row is about.
tshark's expert tap reports how many times something happened and never which packets, so the row cannot carry frame numbers. What it can carry is the text, and Wireshark exposes that as a filterable field - so the row turns into a question the packet list can answer.
type HierarchyRow ¶ added in v1.1.0
HierarchyRow is one protocol in `tshark -z io,phs`.
Depth is how deep the protocol sits under the ones carrying it - frame at 0, eth at 1, ip at 2 - taken from the indentation, which is the only place tshark states it.
func ParseHierarchy ¶ added in v1.1.0
func ParseHierarchy(out string) []HierarchyRow
ParseHierarchy reads the output of `tshark -z io,phs`.
The format is a rule, a title, the filter in force, a blank line, then one indented line per protocol:
frame frames:7 bytes:1027 eth frames:7 bytes:1027
Everything before the first `frames:` line is a preamble, and the rule repeats at the end, so lines are recognised by containing the counts rather than by their position.
func (HierarchyRow) DisplayFilter ¶ added in v1.1.0
func (r HierarchyRow) DisplayFilter() string
DisplayFilter narrows the packet list to the packets containing this protocol. The name tshark prints in this table is the protocol's display filter name, which is why the answer to "what is in this file" can be turned straight into "show me that".
type ILoaderCmds ¶
type ILoaderCmds interface {
Stats(pcapfile string, zargs ...string) pcap.IPcapCommand
}
type IOStatRow ¶ added in v1.2.0
IOStatRow is one time bucket of `tshark -z io,stat,<interval>`.
Label is the bucket as tshark wrote it - "0 <> 5", and "35 <> Dur" for the last one, which runs to the end of the capture rather than to a round number.
func ParseIOStat ¶ added in v1.2.0
ParseIOStat reads the buckets out of `tshark -z io,stat,<interval>`.
The table is drawn with pipes:
| Interval | Frames | Bytes | |---------------------------| | 0 <> 5 | 44 | 3291 | | 35 <> Dur| 12 | 876 |
A data row is recognised by holding tshark's "<>" between its first pair of pipes, which the header and the rules do not.
type IStatsCallbacks ¶
type Loader ¶
type Loader struct {
SuppressErrors bool // if true, don't report process errors e.g. at shutdown
// contains filtered or unexported fields
}
type SeverityTotal ¶ added in v1.1.0
SeverityTotal is how many expert items of one severity the whole capture has, as tshark states it in each section heading: "Notes (430012)".
The number was being read and thrown away - expertSectionName kept the word and dropped what was in the brackets - so the program knew a capture had 430,012 note-level events and printed nothing resembling that anywhere.
func ExpertTotals ¶ added in v1.1.0
func ExpertTotals(out string) []SeverityTotal
ExpertTotals reads the section headings of `tshark -z expert`, in the order tshark printed them, which is worst first.
type Stat ¶
type Stat struct {
// Name titles the dialog.
Name string
// Command is the minibuffer command that opens it.
Command string
// Key is the single keypress that opens it, from the main view and from
// the Analysis menu alike. One letter per view is how k9s and lazygit are
// navigated, and a view reachable only by typing its name is a view most
// people never find.
Key rune
// Summary is the one-line description shown in the menu and help.
Summary string
// contains filtered or unexported fields
}
Stat describes one tshark statistic and how to ask for it.
func (Stat) IgnoresFilter ¶ added in v1.2.0
IgnoresFilter is whether this statistic is computed over the whole capture whatever the display filter says, so that the caller can say so rather than claiming a narrowing that did not happen.
func (Stat) ZArg ¶
ZArg builds the -z argument, narrowing the statistic to displayFilter when one is set.
tshark reads everything after the statistic's own arguments as the filter, so a filter containing commas - "tcp.port in {80,443}" is ordinary Wireshark syntax - is passed through whole and needs no escaping.
type TreeRow ¶ added in v1.1.0
TreeRow is one line of a tshark packet-counter table - the shape shared by `-z http,tree`, `-z dns,tree` and the rest of the ",tree" statistics.
Depth is how far the row is indented, which is the only place tshark says that "404 Not Found" belongs under "4xx: Client Error".
Parent is the name of the row this one is indented under, because the same name means different things in different sections: "A" under Query Type is what was asked for, and "A" under Answer Type is what came back.
Percent and Average are kept as tshark printed them. They are formatted numbers, and the format follows the machine's locale: this project has already been bitten by digit grouping that appears on one CI runner and not another, and the same table prints "33,33%" where another machine prints "33.33%". Parsing them into floats would mean guessing which convention produced them, to print them again immediately.
func NonEmptyRows ¶ added in v1.1.0
NonEmptyRows drops the rows tshark counted at nothing.
These tables are fixed skeletons: every HTTP status class it knows about, every DNS statistic it can collect, present in the capture or not. On a capture with three responses that is four useful lines under sixteen empty ones, and the empty ones are what the eye lands on first. What is in the capture is the question being asked.
A row is kept if anything under it was counted, even when it was not itself: tshark's DNS table has "Query Stats" at zero with the query statistics beneath it, and dropping the heading would leave its rows indented under nothing.
func ParseTree ¶ added in v1.1.0
ParseTree reads a tshark packet-counter table.
The format is a rule, a title, a header, a rule, the rows, and a closing rule:
HTTP / Packet Counter: Packet Type Count Average ... Percent ... ----------------------------------------------------------------------- Total HTTP Packets 3 100% HTTP Response Packets 3 100,00% 2xx: Success 1 33,33% 200 OK 1 100,00%
The columns are fixed-width and the header names them, so the header is what says where Count and Percent begin. Reading them by field position instead would break on the first row whose name contains a space, which is most of them.
The header is found by the two column names this reads, not by the name of the first column: Wireshark calls it "Packet Type" on some builds and "Topic / Item" on others, and CI found that difference between two runners on the same day. Count and Percent are the columns being read, so they are the right thing to require.