Packet trace

The Packet trace feature provides three levels of inspection for packets: accounting, summary, and path data. Each level provides a detailed view of packet processing at the cost of some packet processing capability. However, Packet Trace limits inspection to packets that match the debug platform condition statements, and is a viable option even under heavy-traffic situations in customer environments.

The following table explains the three levels of inspection provided by packet trace.

Table 1. Packet trace levels

Packet trace level

Description

Accounting

Packet-Trace accounting provides a count of packets that enter and leave the network processor. Packet-Trace accounting is a lightweight performance activity, and runs continuously until it is disabled.

Summary

At the summary level of packet trace, data is collected for a finite number of packets. Packet-Trace summary tracks the input and output interfaces, the final packet state, and punt, drop, or inject packets, if any. Collecting summary data adds to additional performance compared to normal packet processing, and can help to isolate a troublesome interface.

Path data

The packet-trace path data level provides the greatest level of detail in packet trace. Data is collected for a finite number of packets. Packet-Trace path data captures data, including a conditional debugging ID that is useful to correlate with feature debugs, a timestamp, and also feature-specific path-trace data.

Path data also has two optional capabilities: packet copy and Feature Invocation Array (FIA) trace. The packet-copy option enables you to copy input and output packets at various layers of the packet (layer 2, layer 3 or layer 4). The FIA- trace option tracks every feature entry invoked during packet processing and helps you to know what is happening during packet processing.

Note

 
Collecting path data consumes more packet-processing resources, and the optional capabilities incrementally affect packet performance. Therefore, path-data level should be used in limited capacity or in situations where packet performance change is acceptable.

Usage guidelines

Consider the following best practices while configuring the Packet-Trace feature:

  • Use of ingress conditions when using the Packet-Trace feature is recommended for a more comprehensive view of packets.

  • Packet-trace configuration requires data-plane memory. On systems where data-plane memory is constrained, carefully consider how you will select the packet-trace values. A close approximation of the amount of memory consumed by packet trace is provided by the following equation:

memory required = (statistics overhead) + number of packets * (summary size + data size + packet copy size).

When the Packet-Trace feature is enabled, a small, fixed amount of memory is allocated for statistics. Similarly, when per-packet data is captured, a small, fixed amount of memory is required for each packet for summary data. However, as shown by the equation, you can significantly influence the amount of memory consumed by the number of packets you select to trace, and whether you collect path data and copies of packets.

Configure packet trace

Perform the following steps to configure the packet trace feature.


Note
The amount of memory consumed by the Packet-Trace feature is affected by the packet-trace configuration. You should carefully select the size of per-packet path data and copy buffers and the number of packets to be traced in order to avoid interrupting normal services. You can check the current data-plane DRAM memory consumption by using the show platform hardware qfp active infrastructure exmem statistics command.

SUMMARY STEPS

  1. enable
  2. debug platform packet-trace packet pkt-num [fia-trace | summary-only] [circular] [data-size data-size ]
  3. debug platform packet-trace punt
  4. debug platform condition [ipv4 | ipv6] [interface interface ][access-list access-list -name | ipv4-address / subnet-mask | ipv6-address / subnet-mask ] [ingress| egress]
  5. debug platform condition start
  6. debug platform condition stop
  7. show platform packet-trace {configuration | statistics | summary | packet {all | pkt-num }}
  8. clear platform condition all
  9. exit

DETAILED STEPS

  Command or Action Purpose

Step 1

enable

Example:


Router> enable

Enables the privileged EXEC mode. Enter your password if prompted.

Step 2

debug platform packet-trace packet pkt-num [fia-trace | summary-only] [circular] [data-size data-size ]

Example:


Router# debug platform packet-trace packets 2048 summary-only

Collects summary data for a specified number of packets. Captures feature path data by the default, and optionally performs FIA trace.

pkt-num —Specifies the maximum number of packets maintained at a given time.

fia-trace —Provides detailed level of data capture, including summary data, feature-specific data. Also displays each feature entry visited during packet processing.

summary-only —Enables the capture of summary data with minimal details.

circular —Saves the data of the most recently traced packets.

data-size —Specifies the size of data buffers for storing feature and FIA trace data for each packet in bytes. When very heavy packet processing is performed on packets, users can increase the size of the data buffers if necessary. The default value is 2048.

Step 3

debug platform packet-trace punt

Example:


Router# debug platform packet-trace punt

Enables tracing of punted packets from Layer2 to Layer3.

Step 4

debug platform condition [ipv4 | ipv6] [interface interface ][access-list access-list -name | ipv4-address / subnet-mask | ipv6-address / subnet-mask ] [ingress| egress]

Example:


Router# debug platform condition interface g0/0/0 ingress

Specifies the matching criteria for tracing packets. Provides the ability to filter by protocol, IP address and subnet mask, access control list (ACL), interface, and direction.

Step 5

debug platform condition start

Example:


Router# debug platform condition start

Enables the specified matching criteria and starts packet tracing.

Step 6

debug platform condition stop

Example:


Router# debug platform condition start

Deactivates the condition and stops packet tracing.

Step 7

show platform packet-trace {configuration | statistics | summary | packet {all | pkt-num }}

Example:


Router# show platform packet-trace 14

Displays packet-trace data according to the specified option. See {start cross reference} Table 21-1 {end cross reference} for detailed information about the show command options.

Step 8

clear platform condition all

Example:


Router(config)# clear platform condition all

Removes the configurations provided by the debug platform condition and debug platform packet-trace commands.

Step 9

exit

Example:


Router# exit

Exits the privileged EXEC mode.

Displaying Packet-Trace Information

Use these show commands to display packet-trace information.

Table 2. show Commands

Command

Description

show platform packet-trace configuration

Displays packet trace configuration, including any defaults.

show platform packet-trace statistics

Displays accounting data for all the traced packets.

show platform packet-trace summary

Displays summary data for the number of packets specified.

show platform packet-trace {all | pkt-num } [decode]

Displays the path data for all the packets or the packet specified. The decode option attempts to decode the binary packet into a more human- readable form.

Remove packet trace data

Use these commands to clear packet-trace data.

Table 3. clear Commands

Command

Description

clear platform packet-trace statistics

Clears the collected packet-trace data and statistics.

clear platform packet-trace configuration

Clears the packet-trace configuration and the statistics.