# Trace and Replay Tools

The LunarG Vulkan SDK includes application trace, replay, and validation programs and libraries.

## Tracing and Trace Files

The LunarG Vulkan SDK provides the capability to trace Vulkan applications. The SDK includes executables and libraries to trace both local and remote apps.

When tracing, the tools record the application's Vulkan API calls to a file named with a `.vktrace` suffix. The call information is stored in the trace file in a compact binary format.

The trace program is named `vktrace`. Options to the `vktrace` command include:

Trace Option | Description | Default
--- | --- | ---
-a <string> ‑‑Arguments <string> | Command line arguments to pass to the application to be traced | none
-o <string> ‑‑OutputTrace <string> | Name of the generated trace file | required
-p <string> ‑‑Program <string> | Name of the application to trace | if not provided, server mode tracing is enabled
-ptm <bool> ‑‑PrintTraceMessages <bool> | Print trace messages to console | on
-s <string> ‑‑Screenshot <string> | Comma-separated list of frame numbers of which to take screen shots | no screenshots
-w <string> ‑‑WorkingDir <string> | Alternate working directory | the application's directory
-P <string> ‑‑PMB <bool> | Optimize trace of persistently mapped buffers | on
-v <string> ‑‑Verbosity <string> | Verbosity mode - "quiet", "errors", "warnings", or "full" | errors

In local tracing mode, both the `vktrace` and application executables reside on the same system.

An example command to trace the SDK sample `cube` application in local mode follows.

Linux shell:

    $ cd examples/build
    $ vktrace -p ./cube -o cubetrace.vktrace

Windows Powershell:

    PS> cd C:\Users\<Name>\Desktop
    PS> vktrace -p C:\VulkanSDK\<Version>\Bin\cube.exe -o cubetrace.vktrace

Note: Subsequent command examples in this document are written using Linux shell commands. These example commands can be translated and used as Windows Powershell commands.

Trace packets are written to the file `cubetrace.vktrace` in the local directory. Output messages from the replay operation are written to `stdout`.

Important: Subsequent `vktrace` runs with the same `-o` option value will overwrite the trace file, preventing the generation of multiple, large trace files. Be sure to specify a unique output trace file name for each `vktrace` invocation if you do not desire this behaviour.

## Client/Server Mode

The tools also support tracing Vulkan applications in client/server mode, where the trace server resides on a local or a remote system.

### Server

In client/server mode, the `vktrace` server is started without specifying the `-p` or `--program` option. Invoked in this fashion, the `vktrace` enters a waiting mode for trace packets.

    $ mkdir examples/traces
    $ cd examples/traces
    $ vktrace -o cubetrace_s.vktrace
    No program (-p) parameter found: Running vktrace as server.

Trace files will be written to `cubetrace_s<``N``>.vktrace`, with the trace server incrementing `N` for each unique run of the application after the first.

### Client

The tracer is implemented as a Vulkan layer. When tracing in server mode, the local or remote client must enable the `Vktrace` layer. The `Vktrace` layer must be the first layer identified in each of the `VK_INSTANCE_LAYERS` lists.

    $ export VK_INSTANCE_LAYERS=Vktrace

#### Local Client

Local client/server mode is particularly useful for Vulkan applications with multiple runtime options or complicated startup.

In local client/server mode, the tracer layer must be eanbled before the local client application to be traced is launched.

    $ cd examples/build
    $ export VK_INSTANCE_LAYERS=Vktrace
    $ ./cube

The generated trace file is found at `examples/traces/cubetrace_s0.vktrace`.

Note: The `cube` application is used to demonstrate tracing in client/server mode. `cube` is a very simple application, and would not be traced in this mode in practice.

#### Remote Client

Remote client/server mode is useful if the client is a mobile device or running in a lightweight environment that might not have the disk or other capabilities to store large trace files.

In remote client/server mode, the remote client must additionally identify the IP address of the trace server system.

    $ cd examples/build
    $ export VKTRACE_LIB_IPADDR=<ip address of trace server system>
    $ export VK_INSTANCE_LAYERS=Vktrace
    $ ./cube

The generated trace file is located at `examples/traces/cubetrace_s1.vktrace` on the remote trace server system.

## Replay

The LunarG Vulkan SDK provides the capability to replay a Vulkan application trace.

Important: Trace files generated with early release versions of the LunarG Vulkan SDK may not be replayable with tools from later LunarG Vulkan SDKs, particularly until the Vulkan specification is finalized and officially released by Khronos.

Important: Trace files generated on one GPU architecture are not currently replayable on another GPU architecture.

The trace replay program is `vkreplay`. `vkreplay` options include:

Replay Option | Description | Default
--- | --- | ---
-o <string> ‑‑Open <string> | Name of trace file to open and replay | required
-l <int> ‑‑NumLoops <int> | Number of times to replay the trace file | 1
-lsf <int> ‑‑LoopStartFrame <int> | The start frame number of the loop range | 0
-lef <int> ‑‑LoopEndFrame <int> | The end frame number of the loop range | the last frame in the tracefile
-s <string> ‑‑Screenshot <string> | Comma-separated list of frame numbers of which to take screen shots | no screenshots
-v <string> ‑‑Verbosity <string> | Verbosity mode - "quiet", "errors", "warnings", or "full" | errors

To replay the cube application trace first captured in the example above:

    $ cd examples/build
    $ vkreplay -o cubetrace.vktrace -l 5

If the trace is rather short, the replay may finish quickly. Specify the `-l` or `--NumLoops` option to replay the trace `NumLoops` option value times.

Output messages from the replay operation are written to `stdout`.

## Replayer Interaction with Layers

The Vulkan validation layers may be enabled for trace replay. Replaying a trace with layers activated provides many benefits. Developers can take advantage of new validation capabilities as they are developed with older and existing trace files.

To activate specific layers on a trace replay, set the `VK_INSTANCE_LAYERS` environment variable to a colon-separated list of layer names before replaying the trace. Refer to the Vulkan Validation and Debugging Layers guide for additional information on layers and how to configure layer output options.

## vktraceviewer

The Vulkan SDK includes vktraceviewer. This tool allows interactive creation and viewing of Vulkan trace files. In the future, it will include support for interactively playing back trace files. This is alpha software.

In order to run vktraceviewer on Linux, Qt5 libraries need to be installed on the system.

## Persistently Mapped Buffers and vktrace

If a Vulkan program uses persistently mapped buffers (PMB) that are allocated via vkMapMemory, vktrace can track changes to PMB and automatically copy modified PMB pages to the trace file, rather than requiring that the Vulkan program call vkFlushMappedMemoryRanges to specify what PMB buffers should be copied. On Windows, the trace layer detects changes to PMB pages by setting the PAGE_GUARD flag for mapped memory pages and installing an exception handler for PAGE_GUARD that keeps track of which pages have been modified. On Linux, the trace layer detects changes to PMB pages by examining /proc/self/pagemap.

Tracking of changes to PMB using the above techniques is enabled by default. If you wish to disable PMB tracking, it can be disabled by with the `--PMB false` option to the vktrace command. Disabling PMB tracking can result in some mapped memory changes not being detected by the trace layer, a larger trace file, and/or slower trace/replay.

## Trace Tools Enviroment Variables

Several enviroment variables can be set to change the behavior of vktrace/vkrepay:

- VKTRACE_PMB_ENABLE

  VKTRACE_PMB_ENABLE enables tracking of PMB if its value is 1. Other values disable PMB tracking. If this environment variable is not set, PMB tracking is enabled. When creating a trace using client/server mode, set this variable to 0 when starting the client if you wish to disable PMB tracking.

- VKTRACE_PAGEGUARD_ENABLE_READ_PMB

  VKTRACE_PAGEGUARD_ENABLE_READ_PMB enables read PMB support if set to a non-NULL value. If PMB data changes comes from the GPU side, PMB tracking does not usually capture those changes. This environment variable is used to enable capture of such GPU initiated PMB data changes. It is supported only on Windows.

- VKTRACE_PAGEGUARD_ENABLE_READ_POST_PROCESS

  VKTRACE_PAGEGUARD_ENABLE_READ_POST_PROCESS, when set to a non-null value, enables post processing when read PMB support is enabled. When VKTRACE_PAGEGUARD_ENABLE_READ_PMB is set, PMB processing will sometimes miss writes following reads if writes occur on the same page as a read. Set this environment variable to enable post processing to fix missed pmb writes. It is supported only on Windows.