ntinfo

Reference Documentation

product_line_custom
Napatech SmartNIC
category
Reference Information

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.