VAITRACE Usage - 1.4 English

Vitis AI User Guide (UG1414)

Document ID
Release Date
1.4 English
Command Line Usage
$ vaitrace --help
usage: Xilinx Vitis AI Trace [-h] [-c [CONFIG]] [-d] [-o [TRACESAVETO]] [-t [TIMEOUT]] [-v]

  cmd		Command to be traced
-b                 Bypass mode, just run command and by pass vaitrace, for debug use
  -c [CONFIG]        Specify the configuration file
  -o [TRACESAVETO] Save trace file to
  -t [TIMEOUT]      Tracing time limitation
  -v                 Show version
Important and frequently-used arguments:
  • cmd: cmd is your executable program of Vitis-AI that want to be traced
  • -t: Controlling the tracing time (in seconds) starting from the [cmd] being launched, the default value is 3. In other words, if no -t is specified for vaitrace, the tracing will stop after [cmd] running for 3 seconds. The [cmd] will continue to run as normal, but it will stop collecting tracing data.

    It is recommended that trace is about 50~100 images at once
    • Less then 50 may not be enough for some statistic information.
    • More then 100 will slow down the system significantly.
  • -o: Where to save trace file (.xat), by default, the .xat file will be saved at the working directory, and the file name will be the same as the executable program and with a .xat as suffix.
  • -c: You can start a tracing with more custom options by writing these options on a json configuration file and specify the configuration by -c. Details of configuration file will be explained in the next section.
  • Others arguments are used for debug


It is recommended to use a configuration file to record trace options for vaitrace. User can start a trace with configuration by using vaitrace -c trace_cfg.json.

Configuration priority: Configuration File > Command Line > Default

Here is an example of vaitrace configuration file.
  "options”: {
      "runmode": "normal",
      "cmd": "/usr/share/vitis-ai-library/sample/classification/test_jpeg_classification resnet50 sample.jpg",
      "output": "./trace_resnet50.xat",
      "timeout": 3
  "trace": {
      "enable_trace_list": ["vitis-ai-library", "vart", "custom"],
      "trace_custom": []
Table 1. The Content of the Configuration File
Key Name Value Type Description
options   object Vaitrace options
cmd string the same with command line argument cmd
output string the same with command line argument -o
timeout integer the same with command line argument -t
runmode string Xmodel run mode control, can be “debug” or “normal”, if runmode == “debug” VART will control xmodel run in a debug mode by using this, user can achieve fine-grained profiling for xmodel. For .elf type mode, only "normal" is valid.
trace   object  
  enable_trace_list list Built-in trace function list to be enabled, available value "vitis-ai-library", "vart", “opencv”, "custom", custom for function in trace_custom list
trace_custom   list The list of functions to be traced that are implemented by user. For the name of function, naming space are supported. You can see an example of using custom trace function later in this document