NAME
ptrace, tron, pm – trace processes

SYNOPSIS
ptrace [ –dgpw ] file

tron [ –f file ] [ –o ofile ] cmd [ arg... ]

pm [ –p nproc ] [ –r nround ] [ –c ncpu ] [ –i nio ] [ –s nstk ] [ –w sleep ]

DESCRIPTION
Ptrace plots and dumps generic process traces previously retrieved from ptrace(3). Unlike with trace(1) and trace(3), the tracing and traced machines can be of different architectures, and tracing is designed for processes in general, and not just real–time ones.

Events are retrieved from file, which is a text file with trace events. Flag –d indicates that file uses the raw format provided by the ptrace(3) device. But note that ptrace stops reading upon EOF, which makes it unsuitable for reading ptrace(3) directly.

By default, the program prints events to standard output in a readable format. The output can be used later as input.

Under flag –g the program draws a plot that can be inspected using the mouse and the keyboard. A new window is used to plot the diagram if –w is given, otherwise, the program uses the window it runs on. It is advisable to use –w if commands causing prints are also used. Flag –p makes the program print events even when –g is given.

Typing q makes the program quit.

In the plot, the left column shows pids and the machine they are running on. Red lines indicate waiting processes, green lines ready processes, and blue lines running processes. Traps and faults are shown below the process line and system calls are shown above.

The plot scale reflects actual time. You might have too zoom in to see some interesting events otherwise merged due to the scale. Placing the mouse near a process line updates the status information shown, including time.

Arrow keys can be used to zoom in (up), out (down), and to move left (left) and right (right). A click on the left (or right) part of the top line with the mouse moves left (or right). A sweep with mouse button 1 zooms into the time window selected.

The Esc key restarts the plot using the original position and scale.

A sweep with button 2 saves the events selected in the file ptrace.out. A sweep with button 3 prints on the standard output the events in the rectangle selected (excluding processes out of the rectangle). Horizontal sweeps select the process where the sweep happens.

A click with the mouse button 3 plumbs the clicked event to the editor. The file name used is ptrace.out when the input uses a device format.

The space key freezes the statistics reported when moving the mouse.

The p key prints the events currently shown in the window. Those too small to be individually plotted are also printed.

The s key saves the events shown into the file named ptrace.out.

Tron is a helper to collect traces for commands. It executes cmd with args activating the trace for it (and descendant processes). Flag –f selects an alternate tracing device.

Flag –o causes tron to read events from the trace device and dump the output to file in the format used by the device. Such output file can later be used with ptrace to inspect what happen, and also to convert it to a textual format. The program ceases collecting events one second after the traced command exits.

Pm is a profile–me program generating a deterministic load with the given numbers of processes, rounds, etc.

EXAMPLE
Capture a trace for a compilation:
term% troff –o tr.out mk all

Print the events contained in the trace.
term% ptrace –d tr.out
00048526953      121 06 mk     Ready    Ready         4 0x0
00048537030      121 04 mk     Run      Run           3 0x0
...

This output can be saved and later used as input for

Convert the dump to a textual format and run ptrace on it using a different window, so we can still use standard output for printing:
term% ptrace –d tr.out >tr.txt
term% ptrace –wg tr.txt

FILES
/dev/ptrace            trace event file
/sys/include/ptrace.h   trace event data structures.
ptrace.out             output for save command.

SOURCE
/sys/src/cmd/ptrace

SEE ALSO
proc(3), trace(1).

BUGS
To avoid extra interference from the tracing tools, the device does not block the reader, and thus the tools must poll the device.

To honor the plot scale, some events do not show up unless you zoom enough; although the picture is still accurate.

Should probably replace trace(1).

Copyright © 2024 Plan 9 Foundation. All rights reserved.