.. _clicmd_src_plugins_dispatch-trace:

===============================================================
Dispatch-trace cli reference
===============================================================

pcap dispatch trace
-------------------------------------------------------------------------

.. code-block:: console

    pcap dispatch trace [on|off] [max <nn>] [file <name>] [status]
                  [buffer-trace <input-node-name> <nn>][post-mortem]



This command is used to start or stop pcap dispatch trace capture, or show
the capture status.

This command has the following optional parameters:

- **on|off** - Used to start or stop capture.
- **max <nn>** - Depth of local buffer. Once ``nn`` number
    of packets have been received, buffer is flushed to file. Once another
    ``nn`` number of packets have been received, buffer is flushed
    to file, overwriting previous write. If not entered, value defaults
    to 100. Can only be updated if packet capture is off.
- **file <name>** - Used to specify the output filename. The file will
    be placed in the ``/tmp`` directory, so only the filename is
    supported. Directory should not be entered. If file already exists, file
    will be overwritten. If no filename is provided, ``/tmp/vpe.pcap``
    will be used. Can only be updated if packet capture is off.
- **status** - Displays the current status and configured attributes
    associated with a packet capture. If packet capture is in progress,
    ``status`` also will return the number of packets currently in
    the local buffer. All additional attributes entered on command line
    with ``status`` will be ignored and not applied.


Example of how to display the status of capture when off:


.. code-block:: console

    pcap dispatch trace status
    
    max is 100, for any interface to file /tmp/vpe.pcap
    pcap dispatch capture is off...
    


Example of how to start a dispatch trace capture:


.. code-block:: console

    pcap dispatch trace on max 35 file dispatchTrace.pcap
    
    pcap dispatch capture on...
    


Example of how to start a dispatch trace capture with buffer tracing


.. code-block:: console

    pcap dispatch trace on max 10000 file dispatchTrace.pcap   buffer-trace dpdk-input 1000
    
    pcap dispatch capture on...
    


Example of how to display the status of a tx packet capture in progress:


.. code-block:: console

    pcap trace tx status
    
    max is 35, dispatch trace to file /tmp/vppTest.pcap
    pcap tx capture is on: 20 of 35 pkts...
    


Example of how to stop a tx packet capture:


.. code-block:: console

    vppctl pcap dispatch trace off
    
    captured 21 pkts...
    saved to /tmp/dispatchTrace.pcap...
    Example of how to start a post-mortem dispatch trace:
    pcap dispatch trace on max 20000 buffer-trace
        dpdk-input 3000000000 post-mortem
    



Declaration: ``pcap_dispatch_trace_command`` `src/plugins/dispatch-trace/main.c line 497 <https://github.com/FDio/vpp/blob/master//src/plugins/dispatch-trace/main.c#L497>`_

Implementation: ``dispatch_trace_command_fn``