Re: [PATCH v2] docs: add workload-tracing document to admin-guide

[Bagas Sanjaya]

On Fri, Jan 27, 2023 at 04:46:16PM -0700, Shuah Khan wrote:
> +strace tool can be used to trace system calls made by a process and signals
> +it receives. a process to the perf, stress-ng, paxtest workloads. System

"... to trace system calls made by a process (which can be perf, stress-ng,
paxtest workloads, or neither)."

> +Before we can get started we will have to get our system ready. We assume

"Before we can get started the system must be prepared first."

> +Browsing kernel sources ::

"To browse kernel sources, you will need:"

> +Workload overview
> +=================
> +
> +We used strace to trace perf bench, stress-ng and paxtest workloads to

"In this section, we use strace to trace ..."

> +show how to analyze a workload and identify Linux subsystems used by
> +these workloads. We hope this process can be applied to trace workload(s).
> +We will go over the workloads first.

"This process can also be applied to trace other workloads."

> +
> +perf bench (all) workload:
> +--------------------------
> +
> <snipped>
> +
> +Stress-ng netdev stressor workload:
> +-----------------------------------
> +
> <snipped>
> +
> +paxtest kiddie workload:
> +------------------------
> +
> <snipped>

Drop trailing colon from these subsection texts.

> +We used the “-c” option to gather fine grained information.

```
The basic usage is strace <command>. To run verbose tracing, specify -v
to strace. To generate the report, specify -c option.
```

> +Now let’s look at `cscope <https://cscope.sourceforge.net/>`_, a command
> +line tool for browsing C, C++ or Java code-bases. We can use it to find
> +all the references to a symbol, global definitions, functions called by a
> +function, functions calling a function, text strings, regular expression
> +patterns, files including a file.
> +
> +We can use cscope to find which system call belongs to which subsystem.
> +This way we can find the kernel subsystems used by a process when it is
> +executed. To use it navigate to the source code directory. Here we are
> +analyzing the kernel source tree.

I guess "you" is better fit for the wording above?

> +We used perf stat and perf bench options. For a detailed information on the
> +perf tool, run perf -h.

"In this section, we highlight stat and bench options. For help on other
options, see perf -h."

> +**perf bench all** command runs the following benchmarks: ::

Either don't markup that command or inline it (``perf bench all``).
Also, use bullet list for benchmarking list below.

> +
> +  sched/messaging
> +  sched/pipe
> +  syscall/basic
> +  mem/memcpy
> +  mem/memset
> +

> +The netdev stressor starts N workers that exercise various netdevice ioctl
> +commands across all the available network devices. The following ioctls are
> +exercised: ::
> +
> +  SIOCGIFCONF, SIOCGIFINDEX, SIOCGIFNAME, SIOCGIFFLAGS
> +  SIOCGIFADDR, SIOCGIFNETMASK, SIOCGIFMETRIC, SIOCGIFMTU
> +  SIOCGIFHWADDR, SIOCGIFMAP, SIOCGIFTXQLEN

Again, use bullet list instead.

> +
> +The following command runs the stressor: ::
> +
> +  stress-ng --netdev 1 -t 60 --metrics command.

Simply end the sentence with double colon to make the code block above.

> +
> +We can use the perf record command to record the events and information
> +associated with a process. This command records the profiling data in the
> +perf.data file in the same directory.
> +
> +Using the following commands you can record the events associated with the
> +netdev stressor, view the generated report perf.data and annotate the to
> +see the statistics of each instruction of the program. ::

"... view the generated report and statistics::"

> +
> +  perf record stress-ng --netdev 1 -t 60 --metrics command.
> +  perf report
> +  perf annotate
> +
> +What is paxtest and how do we use it?
> +=====================================
> +
> +paxtest is a program that tests buffer overflows in the kernel. It tests
> +kernel enforcements over memory usage. Generally, execution in some memory
> +segments makes buffer overflows possible. It runs a set of programs that
> +attempt to subvert memory usage. It is used as a regression test suite for
> +PaX, and will be useful to test other memory protection patches for the
> +kernel.
> +
> +paxtest provides kiddie and blackhat modes. paxtest kiddie mode runs in
> +normal mode, whereas blackhat mode tries to get around the protection of
> +the kernel testing for vulnerabilities. We focus on the kiddie mode here
> +and combine "paxtest kiddie" run with "perf record" to collect CPU stack
> +traces for the paxtest kiddie run to see which function is calling other
> +functions in the performance profile. Then the "dwarf" (DWARF's CFI - Call
> +Frame Information) mode can be used to unwind the stack. The resulting
> +report can be viewed in call-graph format as follows: ::
> +

"... The resulting reported can be viewed in dwarf call-graph format by::"

> +  perf record --call-graph dwarf paxtest kiddie
> +  perf report --stdio
> +
> +Tracing workloads
> +=================
> +
> +Now that we understand the workloads, let's start tracing them.

What are the workloads? I don't see any definition here.

> +
> +Tracing perf bench all workload
> +-------------------------------
> +
> +Run the following command to trace perf bench all workload: ::
> +
> + strace -c perf bench all
> +
> +**System Calls made by the workload:**

What about third level heading (with tilde underline)?

> +
> +The following table shows you the system calls, number of times the system
> +call was invoked, and the Linux subsystem they fall under.

"Below table is the list of syscalls, with number of times each is invoked,
and the corresponding subsystem:"

> +**System Calls made by the workload:**
> +
> +The following table shows you the system calls, number of times the system
> +call was invoked, and the Linux subsystem they fall under.

Same here.

> +**System Calls made by the workload:**
> +
> +The following table shows you the system calls, number of times the system
> +call was invoked, and the Linux subsystem they fall under.

Again, same here.

But I guess the syscall tables are from the example workload (YMMV)?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature