ntinfo -l [ -n <number> ] [ -r]
ntinfo -x -i <number> [ -a <number> ] [ -e <time> ] [ -n <number> ] [ -o <name> ] [ -t <name> ]
ntinfo -i <number> [ -e <time> ] [ -n <number> ] [ -o <name> ]
|Show help message.|
|Aggregate exported values over time intervals.|
|Collect system information until interrupted with ctrl-c.|
|Specify a different end time in export and report mode. Use the format: YYYY/MM/DD-HH:MM:SS, HH:MM:SS or HH:MM.|
|Specify the unique collection identifier in export and report mode.|
|List the available collections.|
|Limit the number of items in export and report mode.|
|Specify an output file in export and report mode. Output goes to standard output by default.|
|Reverse the order of items in list and export mode.|
|Specify the template used in export mode. The default template is |
|Specify export in comma-separated format.|
The tool serves two purposes. The first is to collect system information, primarily about the utilization of the host buffer system. The second is to export the collected information as comma-separated output, or as a textual report.
The tool operates in one of four modes: collect, list, export, or report mode. The mode depends on the options used, see below:
OPTION | MODE -------------------+------------ -c or --collect | collect -l or --list | list -x or --export | export otherwise | report -------------------+------------
The tool assigns a unique identifier, called the collection identifier or just collection ID, to each collection. When starting in collect mode, the tool prints the current identifier in the terminal window. You can use the list mode to list available collections, including any ongoing collection. You must use the
-i/--id option to specify the collection identifier when you want to create a report for a collection, or export its data.
When in collect mode the tool uses an exclusive lock to ensure that only one instance of the tool collects information. When attempting to run multiple instances of ntinfo, the tool hangs until it can get the collect lock. Although only a single instance may collect information, it is possible to use multiple instances of ntinto in the list, export, or report mode concurrently, and while collecting of information is active.
The tool ensures that the file used to store the collected information does not exceed a configurable limit called the quota. The default quota is one gigabytes, and the maximum quota is ten gigabytes. Upon reaching the limit, the tool deletes old values, starting with the oldest values. It is not necessary to delete information manually.
Collected data can be exported as comma-separated output or used be used for textual reports.
When started in collect mode, the tool runs until it is interrupted with ctrl-c, or the tool fails to communicate with ntservice.
List mode provides a list of the available collections. Each collection is identified by a unique number called the collection identifier.
-i/--id option is used to designate the collection from which the tool uses data in export and report mode.
-r/--reverse option reverses the order of items in list and export mode.
When in export mode the tool prints the collected information as comma-separated output.
-e/--endtime option specifies the time to use as the latest time stamp for a collection. When in export mode, the tool shows the latest information first and works its way backwards (in time), unless the -r/--reverse option is used.
-n/--number option limits the number of data items, which is useful when there are many data entries in a collection.
-o/--output option works in report and export mode. The option denotes a file name to which the tool writes its output.
When using the
-a/--aggregate option in export mode, the tool supports aggregation over time, which means the tool combines multiple sampled values into three values: the minimum, maximum, and average value for all of the sampled values during the aggregation period. The aggregation value is the length of the aggregation period, expressed in seconds. It is likely that a user may specify an aggregation value of 60 (sixty) to aggregate over minutes, or perhaps 300 to aggregate over five-minutes periods, or perhaps even 1800 for half-hour periods; but any positive integer is valid.
The tool collects information once per second, which means it produces a complete set of sampled values each second. However, in terms of export, a user may decide that the frequent sampling results in too much information; or perhaps the data is too fine-grained, which is where aggregation may come handy. For example, it may be useful to limit the amount of exported data by grouping (aggregating) the data into periods of, say, 60 (sixty) seconds, because it is sufficient to know the minimum, maximum, and average values of each of the 60 sampled values (for each type of information in the set of sampled values).
In summary, aggregation serves two purposes: (1) limit the amount of data and (2) automatically calculate the minimum, maximum, and average of the samples values.
Note that aggregation only works for number values; the tool ignores textual values when aggregating.
-t/--template option filters the data items in export mode. The tool provides a brief overview of the available templates by specifying a template named help:
$ /opt/napatech3/bin/ntinfo -x -i 1 -t help Error: Template 'help' specified with -t/--template option is unknown. The following templates are available: hb_util (default) Utilization in percent and full counter. hb_util_pct Utilization in percent. hb_util_cnt Full counter. hb_util_all All host buffer utilization information. hb_map Mapping of host buffer number to adapter number, feed number, and type (rx/tx). ai Adapter information. si System information. all All information.
The tool provides a host buffer utilization report. This report gives an overview of the utilization of the RX host buffers in the system during the past minutes, ten-minutes periods, hours, days, and weeks.
When in report mode, the tool shows the latest information first and works its way backwards (in time).
When exporting data from ntinfo, e.g.,
ntinfo -i 1 -x, each line contains seven values (seven fields), each delimited by comma. Each field/value is enclosed in double quotes.
These are the fields used for exports:
The "utc_time_us" field is the UTC time stamp including microseconds. Thus to get the number of seconds and microseconds parts individually:
ts / 1000000 # ts divided by one million
ts % 1000000 # ts modulus one million
The "local_time" field is a text string that specifies the time stamp in human readable formation, and in the local time zone, e.g.,
"2016/11/24-09:20:12.465736" # Useful when importing into a spreadsheet
The "category" field denotes the logical group that an metric belongs to. Ntinfo provides the following groups:
- ai: adapter information
- si: system information
- hb_map: host buffer mapping
- hb_util: host buffer utilization
A category contains multiple items, each identified by a name, see next paragraph.
The "name" field denotes an item in a category. Ntinfo provides the following names (listed together with the category to which they belong):
|num_adapters||si||Number of adapters in the system|
|num_ports||si||Numbers of ports for an adapter|
|sys_id||si||The driver version|
|avr_front||ai||AVR version of "front" for an adapter|
|avr_main||ai||AVR version of "main" for an adapter|
|bus_id||ai||The bus ID of an adapter (as displayed by the adapterinfo tool)|
|fpga_id||ai||FPGA version for an adapter|
|num_hbs||ai||Number of host buffers|
|num_ports||ai||Number of network ports|
|num_rx_hbs||ai||Number of RX host buffers|
|num_tx_hbs||ai||Number of TX host buffers|
|port_offset||ai||The port offset, relevant when multiple adapter are present, necessary to map virtual to physical ports|
|profile||ai||Driver profile, e.g., "TrafficGen", "CaptureReplay"|
|sdram_size||ai||Amount of SDRAM, e.g., "4 GB"|
|adp||hb_map||Host buffer mapping information for an adapter|
|feed||hb_map||Host buffer feed information|
|type||hb_map||The type of a host buffer, either "rx" or "tx"|
|attached_adapter_num||hb_util||Shows which adapter uses which host buffer|
|hb_deq||hb_util||Current number of segments/slabs dequeued|
|hb_enq_adp||hb_util||Current number of segments/slabs enqueued for the adapter|
|hb_enq_drv||hb_util||Current number of segments/slabs enqueued by the driver|
|hb_full_cnt||hb_util||Total/cumulative number of times a HB has been full|
|hb_size||hb_util||Total/cumulative number of times a HB has been full|
|hb_util_pct||hb_util||Current host buffer utilization in percent|
|num_rx_bytes||hb_util||Total/cumulative number of received bytes|
|num_rx_drop||hb_util||Total/cumulative number of dropped bytes|
|num_rx_frames||hb_util||Total/cumulative number of frames|
|num_streams_for_hb||hb_util||Current number of streams for a host buffer|
|sdram_util_pct||hb_util||Current utilization of the SDRAM in percent|
The "numerator" field denotes a number of something, for instance the number of a host buffer, or an adapter number. A numerator may be empty, i.e., "".
For instance, the following denotes the number of host buffers for adapter one:
"ai", "num_hbs", "1" # Numerator = 1
The "val_type" field denotes the value type of the sampled value. Ntinfo uses the following two value types: r, # real number, e.g., "0", "3.1415927" t, # text, e.g., "188.8.131.52", "TrafficGen" The "value" field denotes the sampled value.
Note: When aggregating during export (ntinfo -x -a <seconds>), ntinfo provides three value fields for numeric items (not text items), namely: "min_value", "max_value", "avg_value" which are the minimum, maximum, and average values for the aggregation period.
Note: Ntinfo omits text types when aggregating.
Begin collecting of system information.
ntinfo -l -n 5
List the five latest collections.
ntinfo -l -n 5 -r
List the five oldest collections.
ntinfo -x -i 1234 -t all -o /tmp/export.csv
Export all information for collection 1234 to the file /tmp/report.txt.
ntinfo -x -i 5678 -t hb_util_all -n 9876 -o /tmp/export.csv
Export all host buffer information for collection 5678 to the file /tmp/export.csv; limit the number of data items to 9876.
ntinfo -i 1234
Show the RX host buffer utilization report for collection 1234.