API: Read Flow Info of an Unlearned Flow

Stateful Flow Management

Platform
Napatech SmartNIC
Content Type
User Guide
Capture Software Version
Link™ Capture Software 12.9

Use this example to handle a flow info record.

Unlearned flow information

When a flow is unlearned i.e. removed from the flow table in the SmartNIC, information about the flow is generated. See Flow unlearning for more information about how a flow can be unlearned. A flow info record includes the following:
  • User-defined flow ID.
  • Number of bytes and frames received in the flow.
  • RX time stamp of the last frame in the flow.
  • Union of all TCP flags observed over the life of the flow.
  • Cause of the flow unlearning.
Note: TCP flags are collected either from the inner layer or the outer layer determined by the IpProtocol configuration in NTPL. If IpProtocol is set to Inner, inner layer TCP sessions are tracked. If it is set to Outer, outer layer TCP sessions are be tracked. If it is set to None (default), TCP sessions are not tracked.

Flow info record

A flow info record can be retrieved using the NT_FlowRead function with the NtFlowInfo_s structure. NtFlowInfo_s is defined as follows:
typedef struct NtFlowInfo_s {
  uint64_t packetsA;/*!< Packet counter for set A */
  uint64_t octetsA; /*!< Byte/octet counter for set A */
  uint64_t packetsB;/*!< Packet counter for set B */
  uint64_t octetsB; /*!< Byte/octet counter for set B */
  uint64_t ts;      /*!< Time stamp in UNIX_NS format of last seen packet */
  uint64_t id;      /*!< The 64-bit user-defined ID from the flow programming operation */
  uint16_t flagsA;  /*!< Bitwise OR of TCP flags for packets in set A */
  uint16_t flagsB;  /*!< Bitwise OR of TCP flags for packets in set B */
  uint8_t cause;    /*!< Unlearn cause (0: Software, 1: Timeout, 2: TCP flow termination */
} NtFlowInfo_t;
Note: The flow info record of an unlearned flow is generated only if the gfi field of NtFlow_s was set to 1 when learning the flow. See API: Learn a Flow for more information about flow learning.

The associated flow can be identified using the id field which contains the user-defined flow identification. See Programming Key ID, key set ID and flow ID.

Two counter sets, A and B are supported. Two separate counter sets can be utilized handling counters for upstream traffic and downstream traffic individually for example. NtFlowInfo_s contains values for both counter sets. By default counter set A is used. It can be configured which counter set to be used using NTPL as shown in the following example.
Assign[StreamId=(0..3); Color=0; Descriptor=DYN4, ColorBits=FlowID] = Upstream and \\
 Key(kd, KeyID=1, CounterSet=CSA) == 4
Assign[StreamId=(0..3); Color=0; Descriptor=DYN4, ColorBits=FlowID] = Downstream and \\
 Key(kd, KeyID=1, FieldAction=Swap, CounterSet=CSB) == 4
In this example, counter set A is used for upstream traffic and counter set B is used for downstream traffic. See the full NTPL command example and descriptions in Flow Management over Network TAP Configuration.

The flagsA and flagsB fields contain nine 1-bit of flags (control bits) for a TCP flow. It can be utilized to track status changes of the TCP session.

The cause field contains what caused the flow unlearning operation. The returned value is one of the following:
  • 0: Unlearned by NT_FlowWrite in the application.
  • 1: Unlearned due to a timeout event because the flow was inactive during the defined period. The time can be configured using the FlowTimeOut parameter in /opt/napatech3/config/ntservice.ini. The default value is 120000 milliseconds as shown in the following example.
    FlowTimeOut = 120000 # 0 .. 4294967295
    Note: Set FlowTimeOut to 0 to disable the timeout feature.
  • 2: Unlearned automatically when the TCP session was terminated. This applies to a TCP flow if the tau field of NtFlow_s was set to 1 when the flow was learned. See API: Learn a Flow.
Note: Automatic TCP flow unlearning can be controlled on a per-flow basis by setting the tau field of NtFlow_s when learning a flow. See API: Learn a Flow
Note: The IpProtocol parameter must be set to either Inner or Outer in NTPL commands to enable tracking of TCP sessions for automatic TCP flow unlearning. If IpProtocol is set to Inner, inner layer TCP sessions are tracked. If IpProtocol is set to Outer, outer layer TCP sessions are be tracked. If it is set to None (default), TCP sessions are not tracked, and TCP flows are not automatically unlearned.

Read flow info records of unlearned flows

The following code snippet shows how to read flow info records of unlearned flows.
  NtFlowInfo_t   flowInfo;

  // For each element in the flow stream queue, print the flow info record.
  while(NT_FlowRead(flowStream, &flowInfo, 0) == NT_SUCCESS) {
    std::cout << "NT_FlowRead of flow ID " << flowInfo.id << std::endl
      << "CSA: Packages: " << flowInfo.packets_a
      << ", Octets: "      << flowInfo.octets_a << std::endl
      << "CSB: Packages: " << flowInfo.packets_b
      << ", Octets: "      << flowInfo.octets_b << std::endl
      << "Time stamp: "    << flowInfo.ts << std::endl
      << "TCP flags A: "   << flowInfo.flags_a
      << ", TCP flags B: " << flowInfo.flags_b << std::endl;

    switch(flowInfo.cause) {
      case 0:  std::cout << "Unlearn cause: Software"             << std::endl; break;
      case 1:  std::cout << "Unlearn cause: Timeout"              << std::endl; break;
      case 2:  std::cout << "Unlearn cause: TCP flow termination" << std::endl; break;
      default: std::cout << "Unlearn cause: Not supported"        << std::endl; break;
    }
  }
After a flow is unlearned, the SmartNIC delivers the flow info record to the host. Up to 65536 records can be stored in the host memory. If the host memory is full, new records from the SmartNIC will be dropped. It is therefore good practice calling NT_FlowRead until no more records are available as shown in this example.
Note: If receiving flow info records is not needed, set the gfi field of NtFlow_s to 0 when learning flows. See API: Learn a Flow.
Note: Flow info records are read from the same flow stream that originally learned the flows.