Cisco Catalyst 8500 and 8500L Series Edge Platforms Software Configuration Guide

PDF

Packet trace

Updated: February 6, 2026

Overview

Explains how to inspect detailed packet processing data based on specific debug conditions. Use this feature to verify policy enforcement and analyze forwarding behaviors without significantly impacting system performance.

Packet trace

A packet trace is a diagnostic feature that

  • provides detailed insight into how data packets are processed within Cisco IOS XE platforms,

  • enables selective debugging and inspection of traffic flow based on user-defined conditions, and

  • has inspection detail levels that can impact device performance depending on the amount of information collected.

You can use packet trace to troubleshoot network issues, verify policy enforcement, and analyze unusual forwarding behaviors directly on the device.

Packet trace feature levels

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, this feature inspects only packets that match the debug platform condition statements. This approach remains viable even during periods of heavy network traffic in customer environments.

Table 1. Packet trace level
Packet trace level Description

Accounting

Provides a count of packets entering and leaving the network processor. This activity runs continuously in a lightweight manner until disabled.

Summary

Collects data for a finite number of packets, including input and output interfaces, final packet state, and the handling of punt, drop, or inject packets. This mode increases processing activity compared to normal operation.

Path data

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). This level uses the most processing resources and is suitable only when performance impact is acceptable.

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.

Best practice for packet trace configuration

Use these best practices when you configure the packet trace feature:

  • Use ingress conditions when configuring the packet trace feature to gain a comprehensive view of packets.

  • If the system has limited data-plane memory, select packet trace values carefully to minimize memory usage.

  • Estimate how much memory you need before you enable packet trace. Limit the number of packets you trace and the amount of data you collect as needed.

You can estimate the required memory for packet trace using this formula:

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

When you enable packet trace, the system allocates a small, fixed amount of memory for statistics. When the system captures per-packet data, each packet summary requires a fixed amount of memory. The total memory consumption depends on how many packets you select for tracing and whether you collect path data and packet copies.

Packet trace display commands

The table provides detailed packet trace information.

These show commands provide detailed packet trace information.

Table 1. 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.

Commands for clearing packet trace data

This section describes the available commands for clearing packet trace data.

Use these commands to clear packet trace data.

Table 1. 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.

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.

Procedure

1.

enable

Example:


Router> enable

Enables the privileged EXEC mode. Enter your password if prompted.
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.
3.

debugplatformpacket-tracepunt

Example:


Router# debug platform packet-trace punt

Enables tracing of punted packets from Layer2 to Layer3.
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.
5.

debug platform condition start

Example:


Router# debug platform condition start

Enables the specified matching criteria and starts packet tracing.
6.

debug platform condition stop

Example:


Router# debug platform condition start

Deactivates the condition and stops packet tracing.
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.
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.
9.

exit

Example:


Router# exit

Exits the privileged EXEC mode.

Packet trace is configured. The device will capture and display packet path data per your configuration.

Packet Trace command examples

This example describes how to configure packet trace and display its results.

This example traces incoming packets to Gigabit Ethernet interface 0/0/2. FIA-trace data is captured for the first 128 packets, and the input packets are copied. Use the show platform packet-trace packet 10 command to display summary data and each feature entry visited during the processing of packet 10.


Router> 
enable
Router# debug platform packet-trace packet 128 fia-trace
Router# debug platform packet-trace punt
Router# debug platform condition interface g0/0/2 ingress
Router# debug platform condition start
Router# ping to UUT
Router# debug platform condition stop
Router# show platform packet-trace packet 10
Packet: 10           CBUG ID: 52
Summary
  Input     : GigabitEthernet0/0/0
  Output    : internal0/0/rp:1
  State     : PUNT 55  (For-us control)
  Timestamp
  Start   : 597718358383 ns (06/06/2016 09:00:13.643341 UTC)
  Stop    : 597718409650 ns (06/06/2016 09:00:13.643392 UTC)
Path Trace
Feature: IPV4
    Input       : GigabitEthernet0/0/0
    Output      : <unknown>
    Source      : 10.64.68.2
    Destination : 224.0.0.102
    Protocol    : 17 (UDP)
    SrcPort   : 1985
    DstPort   : 1985
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : <unknown>
    Entry       : 0x8a0177bc - DEBUG_COND_INPUT_PKT
    Lapsed time : 426 ns
  Feature: FIA_TRACE
 --More--                               Input       : GigabitEthernet0/0/0
    Output      : <unknown>
    Entry       : 0x8a017788 - IPV4_INPUT_DST_LOOKUP_CONSUME
    Lapsed time : 386 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : <unknown>
    Entry       : 0x8a01778c - IPV4_INPUT_FOR_US_MARTIAN
    Lapsed time : 13653 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017730 - IPV4_INPUT_LOOKUP_PROCESS_EXT
    Lapsed time : 2360 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017be0 - IPV4_INPUT_IPOPTIONS_PROCESS_EXT
    Lapsed time : 66 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017bfc - IPV4_INPUT_GOTO_OUTPUT_FEATURE_EXT
 --More--                               Lapsed time : 680 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017d60 - IPV4_INTERNAL_ARL_SANITY_EXT
    Lapsed time : 320 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017a40 - IPV4_VFR_REFRAG_EXT
    Lapsed time : 106 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017d2c - IPV4_OUTPUT_DROP_POLICY_EXT
    Lapsed time : 1173 ns
  Feature: FIA_TRACE
    Input       : GigabitEthernet0/0/0
    Output      : internal0/0/rp:1
    Entry       : 0x8a017940 - INTERNAL_TRANSMIT_PKT_EXT
    Lapsed time : 20173 ns
IOSd Path Flow: Packet: 10    CBUG ID: 52
  Feature: INFRA
    Pkt Direction: IN
    Packet Rcvd From CPP
  Feature: IP
    Pkt Direction: IN
    Packet Enqueued in IP layer
    Source      : 10.64.68.2
    Destination : 224.0.0.102
    Interface   : GigabitEthernet0/0/0
  Feature: UDP
    Pkt Direction: IN
    src         : 10.64.68.2(1985)
    dst         : 224.0.0.102(1985)
    length      : 14
Router# clear platform condition all
Router# exit

Packet trace output for NAT troubleshooting

The output shows that packets are dropped due to NAT configuration on Gigabit Ethernet interface 0/0/0, which enables you to understand that an issue is occurring on a specific interface. You can use this information to limit which packets to trace, reduce the number of packets for data capture, and increase the level of inspection.

This section displays packet trace output for NAT configuration.

Use packet trace to troubleshoot packet drops for a NAT configuration on a Cisco 8500 Series Catalyst Edge Platform Router. Packet trace provides detailed information to help you diagnose an issue, isolate the cause, and find a solution

If you detect issues but are unsure where to begin troubleshooting, consider accessing the packet trace summary for multiple incoming packets.


Router# debug platform condition ingress
Router# debug platform packet-trace packet 2048 summary-only
Router# debug platform condition start
Router# debug platform condition stop
Router# show platform packet-trace summary
Pkt   Input             Output            State  Reason
0     Gi0/0/2.3060      Gi0/0/2.3060      DROP   402 (NoStatsUpdate)
1     internal0/0/rp:0  internal0/0/rp:0  PUNT   21  (RP<->QFP keepalive)
2     internal0/0/recycle:0  Gi0/0/2.3060 FWD

The output shows that packets are dropped due to NAT configuration on Gigabit Ethernet interface 0/0/0, which enables you to understand that an issue is occurring on a specific interface. Using this information, you can limit which packets to trace, reduce the number of packets for data capture, and increase the level of inspection.


Router# debug platform packet-trace packet 256
Router# debug platform packet-trace punt
Router# debug platform condition interface Gi0/0/0
Router# debug platform condition start
Router# debug platform condition stop
Router# show platform packet-trace summary 
Router# show platform packet-trace 15
Packet: 15          CBUG ID: 238
Summary
Input     : GigabitEthernet0/0/0
Output    : internal0/0/rp:1
State     : PUNT 55  (For-us control)
Timestamp
Start   : 1166288346725 ns (06/06/2016 09:09:42.202734 UTC)
Stop    : 1166288383210 ns (06/06/2016 09:09:42.202770 UTC)
Path Trace
Feature: IPV4
Input       : GigabitEthernet0/0/0
Output      : <unknown>
Source      : 10.64.68.3
Destination : 224.0.0.102
Protocol    : 17 (UDP)
SrcPort   : 1985
DstPort   : 1985
IOSd Path Flow: Packet: 15    CBUG ID: 238
Feature: INFRA
Pkt Direction: IN
Packet Rcvd From CPP
Feature: IP
Pkt Direction: IN
Source      : 10.64.68.122
Destination : 10.64.68.255
Feature: IP
Pkt Direction: IN
Packet Enqueued in IP layer
Source      : 10.64.68.122
Destination : 10.64.68.255
Interface   : GigabitEthernet0/0/0
Feature: UDP
Pkt Direction: IN
src         : 10.64.68.122(1053)
dst         : 10.64.68.255(1947)
length      : 48