How to use

Strace configurations

CatStrace runs the Strace command to capture the following system calls:

• open , openat
• read, pread64
• write, pwrite64
• accept, accept4
• connect, socket
• recv, recvfrom, recvmsg
• send, sendto, sendmsg

The following Strace flags are required in order to use CatStrace:

• -o [output file name] - to save strace output to a file.
• -s [buffers size] - to specify the maximum string size to print.
• -tt - to prefix each line of the trace with the wall clock time (including microseconds).
• -yy - to print all available information associated with file descriptors.
• -f - to follow what child procs and threads are doing.

Usage examples

Parse strace output.

To parse Strace output, use CatStrace with the flag --input [filename].

# run strace:
sudo strace -o strace.out -e open,read,write -tt -yy -f -s 4096 cp test.txt test_copy.txt

# run catstrace
sudo catstrace [options] --input [strace_file]

# Example
sudo catstrace --input strace.out

Trace a new process by command (live-mode).

To start tracing a new process and the subsequent process tree, we recommend using this approach.

sudo catstrace [options] [command]

# Example
sudo catstrace cp test.txt test_copy.txt

Trace a currently running process (live-mode).

Sometimes, you want to trace the behavior of an already running process. However, please note that the process tree of the running process will not be traced.

sudo catstrace [options] --pid [pid]

# Example
sudo catstrace --pid 123

Save only the events from specific locations.

To filter relevant events and save only disk events from a specific location we can use the flag --whitelist. This option allows passing a file with all the paths that should be considered when filtering the requests.

For example, whitelist.txt:

# Example (whitelist.txt)
/home/user/test_folder/
STDOUT

The following command will trace the copy of file test.txt to test_copy.txt and save only the disk events from folder /home/user/test_folder/ and from the standard output.

sudo catstrace --whitelist whitelist.txt /bin/cp test.txt test_copy.txt

Show events statistics.

When using the --stats flag, CatStrace will print to the standard output the events statistics.

sudo catstrace --stats /bin/cp test.txt test_copy.txt

Example:

...
2021-01-16 18:38:50,832 INFO [CatStrace.py:256] - Strace Events:
2021-01-16 18:38:50,833 INFO [CatStrace.py:257] - 	Syscall        	Calls	Returns	Errors	Discarded
2021-01-16 18:38:50,833 INFO [CatStrace.py:262] - 	openat    	   27	   27	    0	    0
2021-01-16 18:38:50,833 INFO [CatStrace.py:262] - 	read      	   13	   13	    0	    0
2021-01-16 18:38:50,834 INFO [CatStrace.py:262] - 	pread64   	    8	    8	    0	    0
2021-01-16 18:38:50,834 INFO [CatStrace.py:262] - 	write     	    1	    1	    0	    0

2021-01-16 18:38:50,834 INFO [CatStrace.py:273] - StraceParser Events:
2021-01-16 18:38:50,834 INFO [CatStrace.py:274] - 	Type           	 Saved	Truncated
2021-01-16 18:38:50,835 INFO [CatStrace.py:276] - 	disk_open      	    27	      0
2021-01-16 18:38:50,835 INFO [CatStrace.py:276] - 	disk_read      	    21	      0
2021-01-16 18:38:50,835 INFO [CatStrace.py:276] - 	disk_write     	     1	      0
...

---

See all the available options by running catstrace --help in your terminal.