ntinfo

Reference Documentation
Platform
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.6
Napatech Software Suite: ntinfo
ntinfo
Napatech Software Suite Documentation » Tools

Syntax

ntinfo -c

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> ]

Tool Options

Command Description
-h or --help Show help message.
-a or --aggregate Aggregate exported values over time intervals.
-c or --collect Collect system information until interrupted with ctrl-c.
-e or --endtime 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.
-i or --id> Specify the unique collection identifier in export and report mode.
-l or --list List the available collections.
-n or --number Limit the number of items in export and report mode.
-o or --output Specify an output file in export and report mode. Output goes to standard output by default.
-r or --reverse Reverse the order of items in list and export mode.
-t or --template Specify the template used in export mode. The default template is hb_util.
-x or --export Specify export in comma-separated format.

Introduction

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
   -------------------+------------

Operation Modes

Collect Mode

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

List mode provides a list of the available collections. Each collection is identified by a unique number called the collection identifier.

The -i/--id option is used to designate the collection from which the tool uses data in export and report mode.

The -r/--reverse option reverses the order of items in list and export mode.

Export Mode

When in export mode the tool prints the collected information as comma-separated output.

The -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.

The -n/--number option limits the number of data items, which is useful when there are many data entries in a collection.

The -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.

The -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.

Report Mode

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).

Output

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:

  • utc_time_us
  • local_time
  • category
  • name
  • numerator
  • val_type
  • value

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):

Name Group Description
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., "2.11.3.21", "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.

Examples

  • ntinfo -c
    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.