AggregateCounter

AggregateCounter Element Documentation

NAME

AggregateCounter — Click element; counts packets per aggregate annotation

SYNOPSIS

AggregateCounter([KEYWORDS])

Ports: 1-2 inputs, 1-2 outputs
Processing: agnostic
Drivers: userlevel

DESCRIPTION

AggregateCounter maintains counts of how many packets or bytes it has seen for each aggregate value. Each aggregate annotation value gets a different count. Call its write_file or write_text_file write handler to get a dump of the information.

The freeze handler, and the AGGREGATE_FREEZE and COUNT_FREEZE keyword arguments, can put AggregateCounter in a frozen state. Frozen AggregateCounters only update existing counters; they do not create new counters for previously unseen aggregate values.

AggregateCounter may have one or two inputs. The optional second input is always frozen. (It is only useful when the element is push.) It may also have two outputs. If so, and the element is push, then packets that were counted are emitted on the first output, while other packets are emitted on the second output.

Keyword arguments are:

• BYTES — Boolean. If true, then count bytes, not packets. Default is false.

• IP_BYTES — Boolean. If true, then do not count bytes from the link header. Default is false.

• MULTIPACKET — Boolean. If true, and BYTES is false, then use packets' packet count annotations to add to the number of packets seen. Elements like FromIPSummaryDump set this annotation. Default is true.

• EXTRA_LENGTH — Boolean. If true, and BYTES is true, then include packets' extra length annotations in the byte counts. Elements like FromDump set this annotation. Default is true.

• AGGREGATE_STOP — Unsigned. Stop the router once N distinct aggregates have been seen. Default is never to stop.

• AGGREGATE_FREEZE — Unsigned. Freeze the AggregateCounter once N distinct aggregates have been seen. Default is never to freeze.

• AGGREGATE_CALL — Argument is 'N HANDLER [VALUE]'. Call the given write handler, with the supplied value, once N distinct aggregates have been seen.

  The three AGGREGATE keywords are mutually exclusive. Supply at most one of them.

• COUNT_STOP — Unsigned. Stop the router once the total count (of bytes or packets) has reached or exceeded N. Default is never to stop.

• COUNT_FREEZE — Unsigned. Freeze the AggregateCounter once the total count has reached or exceeded N. Default is never to freeze.

• COUNT_CALL — Argument is 'N HANDLER [VALUE]'. Call the given write handler, with the supplied value, once the total count has reached or exceeded N.

  The three COUNT keywords are mutually exclusive. Supply at most one of them.

• BANNER — String. This banner is written to the head of any output file. It should probably begin with a comment character, like '!' or '#'. Default is empty.

ELEMENT HANDLERS

• write_file (write-only) — Argument is a filename, or '-', meaning standard out. Write a packed binary file containing all current data to the specified filename. The format is a couple text lines, followed by a line containing '!packed_le' or '!packed_be', followed by N 8-byte records. In each record, bytes 1-4 are the aggregate, and bytes 5-8 are the count. Both values are 32-bit integers. The byte order is indicated by the '!packed' line: '!packed_le' means little-endian, '!packed_be' means big-endian.
• write_text_file (write-only) — Argument is a filename, or '-', meaning standard out. Write a text file containing all current data to the specified filename. The format is a couple text lines, followed by N data lines, each containing the aggregate ID in decimal, a space, then the count in decimal.
• write_ip_file (write-only) — Argument is a filename, or '-', meaning standard out. Write a text file containing all current data to the specified filename. The format is as in write_text_file, except that aggregate IDs are printed as IP addresses.
• freeze (read/write) — Returns or sets the AggregateCounter's frozen state, which is 'true' or 'false'. AggregateCounter starts off unfrozen.
• active (read/write) — Returns or sets the AggregateCounter's active state. When AggregateCounter is inactive ('false'), it does not record information about any packets that pass. It starts out active.
• stop (write-only) — When any value is written to this handler, AggregateCounter sets 'active' to false and additionally stops the driver.
• counts_pdf (write-only) — When any value is written to this handler, AggregateCounter will recalculate its counters. The new aggregate identifiers equal the old counts; the new counts represent how many times each old count appeared. The old aggregate identifiers are thrown away. To put it another way, AggregateCounter creates a multiset containing all aggregate counts, then stores each count as an aggregate, with its number of occurrences in the multiset as its count.
• banner (read/write) — Returns or sets the BANNER setting.
• aggregate_call (read/write) — Returns or sets the AGGREGATE_CALL setting.
• count_call (read/write) — Returns or sets the COUNT_CALL setting.
• nagg (read-only) — Returns the number of aggregates that have been seen so far.

NOTES

The aggregate identifier is stored in host byte order. Thus, the aggregate ID corresponding to IP address 128.0.0.0 is 2147483648.

Only available in user-level processes.

EXAMPLES

This configuration reads an IP summary dump in from standard input, aggregates based on destination IP address, and counts packets. When the dump is done, Click will write the aggregate counter's data to standard output, in text form.

  FromIPSummaryDump(-, STOP true)
        -> AggregateIP(ip dst)
        -> ac :: AggregateCounter
        -> Discard;
 
  DriverManager(wait_pause,
        write ac.write_text_file -);

SEE ALSO

AggregateIP, AggregatePacketCounter, FromIPSummaryDump, FromDump

Generated by click-elem2man from ../elements/analysis/aggcounter.hh:7 on 2017/10/17.