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

[Randy Dunlap]

Hi--

On 1/27/23 15:46, Shuah Khan wrote:
> Add a new section to the admin-guide with information of interest to
> application developers and system integrators doing analysis of the
> Linux kernel for safety critical applications.
> 
> This section will contain documents supporting analysis of kernel
> interactions with applications, and key kernel subsystems expectations.
> 
> Add a new workload-tracing document to this new section.
> 
> Signed-off-by: Shefali Sharma <sshefali021@xxxxxxxxx>
> Signed-off-by: Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
> ---
> Changes since v1:
> - Addressed review comments on v1 on long lines, rst syntax, license
> 
>  Documentation/admin-guide/index.rst           |  11 +
>  .../admin-guide/workload-tracing.rst          | 591 ++++++++++++++++++
>  2 files changed, 602 insertions(+)
>  create mode 100644 Documentation/admin-guide/workload-tracing.rst
> 

> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> new file mode 100644
> index 000000000000..43753f3ea915
> --- /dev/null
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -0,0 +1,591 @@
> +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
> +


> +What is perf and how do we use it?
> +====================================
> +
> +Perf is an analysis tool based on Linux 2.6+ systems, which abstracts the
> +CPU hardware difference in performance measurement in Linux, and provides
> +a simple command line interface. Perf is based on the perf_events interface
> +exported by the kernel. It is very useful for profiling the system and
> +finding performance bottlenecks in an application.
> +
> +If you haven't already checkout the Linux mainline repository, you can do

                          checked out

> +so and then build kernel and perf tool: ::
> +
> +  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux
> +  cd linux
> +  make -j3 all
> +  cd tools/perf
> +  make
> +
> +Note: The perf command can be built without building the kernel in the
> +repo and can be run on older kernels. However matching the kernel and

   preferably "repository"

> +perf revisions gives more accurate information on the subsystem usage.
> +
> +We used perf stat and perf bench options. For a detailed information on the
> +perf tool, run perf -h.
> +


Fix table line below:

> +Tracing paxtest kiddie workload
> +-------------------------------
> +
> +Run the following command to trace paxtest kiddie workload: ::
> +
> + strace -c paxtest kiddie
> +
> +**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.
> +
> ++-------------------+-----------+-----------------+----------------------+
> +| System Call       | # calls   | Linux Subsystem | System Call (API)    |
> ++===================+===========+=================+======================+
> +| read              | 3         | Filesystem      | sys_read()           |
> ++-------------------+-----------+-----------------+----------------------+
> +| write             | 11        | Filesystem      | sys_write()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| close             | 41        | Filesystem      | sys_close()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| stat              | 24        | Filesystem      | sys_stat()           |
> ++-------------------+-----------+-----------------+----------------------+
> +| fstat             | 2         | Filesystem      | sys_fstat()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| pread64           | 6         | Filesystem      | sys_pread64()        |
> ++-------------------+-----------+-----------------+----------------------+
> +| access	    | 1         | Filesystem      | sys_access()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| pipe              | 1         | Filesystem      | sys_pipe()           |
> ++-------------------+-----------+-----------------+----------------------+
> +| dup2              | 24        | Filesystem      | sys_dup2()           |
> ++-------------------+-----------+-----------------+----------------------+
> +| execve            | 1         | Filesystem      | sys_execve()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| fcntl             | 26        | Filesystem      | sys_fcntl()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| openat            | 14        | Filesystem      | sys_openat()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| rt_sigaction      | 7         | Signal          | sys_rt_sigaction()   |
> ++-------------------+-----------+-----------------+----------------------+
> +| rt_sigreturn      | 38        | Signal          | sys_rt_sigreturn()   |
> ++-------------------+-----------+-----------------+----------------------+
> +| clone             | 38        | Process Mgmt.   | sys_clone()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| wait4             | 44        | Time            | sys_wait4()          |
> ++-------------------+-----------+-----------------+----------------------+
> +| mmap              | 7         | Memory Mgmt.    | sys_mmap()           |
> ++-------------------+-----------+-----------------+----------------------+
> +| mprotect          | 3         | Memory Mgmt.    | sys_mprotect()       |
> ++-------------------+-----------+-----------------+----------------------+
> +| munmap            | 1         | Memory Mgmt.    | sys_munmap()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| brk               | 3         | Memory Mgmt.    | sys_brk()            |
> ++-------------------+-----------+-----------------+----------------------+
> +| getpid            | 1         | Process Mgmt.   | sys_getpid()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| getuid            | 1         | Process Mgmt.   | sys_getuid()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| getgid            | 1         | Process Mgmt.   | sys_getgid()         |
> ++-------------------+-----------+-----------------+----------------------+
> +| geteuid           | 2         | Process Mgmt.   | sys_geteuid()        |
> ++-------------------+-----------+-----------------+----------------------+
> +| getegid           | 1         | Process Mgmt.   | sys_getegid()        |
> ++-------------------+-----------+-----------------+----------------------+
> +| getppid           | 1         | Process Mgmt.   | sys_getppid()        |
> ++-------------------+-----------+-----------------+----------------------+
> +| arch_prctl        | 2         | Process Mgmt.   | sys_arch_prctl()     |
> ++-------------------+-----------+-----------------+----------------------+
> +
> +Conclusion
> +==========
> +
> +This document is intended to be used as a guide on how to gather fine
> +grained information on the resources in use by workloads using strace.

fine-grained

Thanks.
-- 
~Randy