/proc 2.6.24 changes for guest CPU accounting

/proc 2.6.24 changes for guest CPU accounting

[Michael Kerrisk]

Hi Laurent,

A note and patch from Samuel alerted me to your commits
9ac52315d4cf5f561f36dabaf0720c00d3553162 and
5e84cfde51cf303d368fcb48f22059f37b3872de, which in 2.6.24 changed /proc/stat
and /proc/PID/stat.  Would you please CC me on kernel-userspace interface
changes, so that they have a chance of getting documented in man-pages.

(I see that Andrew P tried to get something added to
Documentation/filesystems/proc.txt, but that doesn't seem to have made it in.)

Below is a patch against the proc.5 man page by Samuel and I to document these
changes.  Do the changes look okay to you?  The first part is the change for
/proc/<pid>/stat, and the other is for /proc/stat.

Cheers,

Michael



===================================================================
--- proc.5      (revision 4046)
+++ proc.5      (working copy)
@@ -753,6 +753,13 @@
  .TP
  \fIdelayacct_blkio_ticks\fP %llu (since Linux 2.6.18)
  Aggregated block I/O delays, measured in clock ticks (centiseconds).
+.TP
+\fIguest_time\fP %lu (since Linux 2.6.24)
+Guest time of the process (time spent running a virtual CPU
+for a guest operating system), in centiseconds.
+.TP
+\fIcguest_time\fP %ld (since Linux 2.6.24)
+Guest time of the process's children, in centiseconds.
  .RE
  .TP
  .I /proc/[number]/statm
@@ -1510,6 +1517,12 @@
  .I steal
  \- stolen time, which is the time spent in other operating systems when
  running in a virtualized environment
+
+Since Linux 2.6.24, there is a ninth column,
+.IR guest ,
+which is the time spent running a virtual CPU for guest
+operating systems under teh control of the Linux kernel.
+.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de
  .TP
  \fIpage 5741 1808\fP
  The number of pages the system paged in and the number that were paged

Re: /proc 2.6.24 changes for guest CPU accounting

[Christian Borntraeger]

Am Sonntag, 22. Juni 2008 schrieb Michael Kerrisk:
> Hi Laurent,
> 
> A note and patch from Samuel alerted me to your commits
> 9ac52315d4cf5f561f36dabaf0720c00d3553162 and
> 5e84cfde51cf303d368fcb48f22059f37b3872de, which in 2.6.24 changed /proc/stat
> and /proc/PID/stat.  Would you please CC me on kernel-userspace interface
> changes, so that they have a chance of getting documented in man-pages.
[...]
> +.TP
> +\fIguest_time\fP %lu (since Linux 2.6.24)
> +Guest time of the process (time spent running a virtual CPU
> +for a guest operating system), in centiseconds.
> +.TP
> +\fIcguest_time\fP %ld (since Linux 2.6.24)
> +Guest time of the process's children, in centiseconds.
[...]
> +
> +Since Linux 2.6.24, there is a ninth column,
> +.IR guest ,
> +which is the time spent running a virtual CPU for guest
> +operating systems under teh control of the Linux kernel.
> +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de

Maybe you should mention that guest time is accounted twice: user and guest. 
So if guest time aware userspace wants to to calcuate user time without 
guests time, it should subtract the guest time from user.

Christian

Re: /proc 2.6.24 changes for guest CPU accounting

[Laurent Vivier]

Le dimanche 22 juin 2008 à 09:31 +0200, Michael Kerrisk a écrit :
> Hi Laurent,

Hi Michael,

> A note and patch from Samuel alerted me to your commits
> 9ac52315d4cf5f561f36dabaf0720c00d3553162 and
> 5e84cfde51cf303d368fcb48f22059f37b3872de, which in 2.6.24 changed /proc/stat
> and /proc/PID/stat.  Would you please CC me on kernel-userspace interface
> changes, so that they have a chance of getting documented in man-pages.
> 
> (I see that Andrew P tried to get something added to
> Documentation/filesystems/proc.txt, but that doesn't seem to have made it in.)
> 
> Below is a patch against the proc.5 man page by Samuel and I to document these
> changes.  Do the changes look okay to you?  The first part is the change for
> /proc/<pid>/stat, and the other is for /proc/stat.

Thank you for that. It seems correct to me (except a typo).

You must also notes that "user time" includes "guest time", if you want
real "user time" you must subtract "guest time".
The "guest time" is included in "user time" to not loose it when the
"reader" is not aware of the "guest time".

> Cheers,
> 
> Michael

Thank you,
Laurent
 
> 
> 
> ===================================================================
> --- proc.5      (revision 4046)
> +++ proc.5      (working copy)
> @@ -753,6 +753,13 @@
>   .TP
>   \fIdelayacct_blkio_ticks\fP %llu (since Linux 2.6.18)
>   Aggregated block I/O delays, measured in clock ticks (centiseconds).
> +.TP
> +\fIguest_time\fP %lu (since Linux 2.6.24)
> +Guest time of the process (time spent running a virtual CPU
> +for a guest operating system), in centiseconds.
> +.TP
> +\fIcguest_time\fP %ld (since Linux 2.6.24)
> +Guest time of the process's children, in centiseconds.
>   .RE
>   .TP
>   .I /proc/[number]/statm
> @@ -1510,6 +1517,12 @@
>   .I steal
>   \- stolen time, which is the time spent in other operating systems when
>   running in a virtualized environment
> +
> +Since Linux 2.6.24, there is a ninth column,
> +.IR guest ,
> +which is the time spent running a virtual CPU for guest
> +operating systems under teh control of the Linux kernel.

typo: "teh" -> "the"

> +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de
>   .TP
>   \fIpage 5741 1808\fP
>   The number of pages the system paged in and the number that were paged
> 
> 
> 
> 
-- 
------------- Laurent.Vivier@bull.net ---------------
"The best way to predict the future is to invent it."
- Alan Kay

Re: /proc 2.6.24 changes for guest CPU accounting

[Michael Kerrisk]

On Mon, Jun 23, 2008 at 10:48 AM, Laurent Vivier
<Laurent.Vivier@bull.net> wrote:
> Le dimanche 22 juin 2008 à 09:31 +0200, Michael Kerrisk a écrit :
>> Hi Laurent,
>
> Hi Michael,
>
>> A note and patch from Samuel alerted me to your commits
>> 9ac52315d4cf5f561f36dabaf0720c00d3553162 and
>> 5e84cfde51cf303d368fcb48f22059f37b3872de, which in 2.6.24 changed /proc/stat
>> and /proc/PID/stat.  Would you please CC me on kernel-userspace interface
>> changes, so that they have a chance of getting documented in man-pages.
>>
>> (I see that Andrew P tried to get something added to
>> Documentation/filesystems/proc.txt, but that doesn't seem to have made it in.)
>>
>> Below is a patch against the proc.5 man page by Samuel and I to document these
>> changes.  Do the changes look okay to you?  The first part is the change for
>> /proc/<pid>/stat, and the other is for /proc/stat.
>
> Thank you for that. It seems correct to me (except a typo).
>
> You must also notes that "user time" includes "guest time", if you want
> real "user time" you must subtract "guest time".
> The "guest time" is included in "user time" to not loose it when the
> "reader" is not aware of the "guest time".

Hi Laurent (and Christian)

So, I just want to confirm.  You are saying that guest_time and
cguest_time are respectively also included in the following fields

              utime %lu
                     The number of jiffies that this process has  been
                     scheduled in user mode.

              [...]

              cutime %ld
                     The number of jiffies that this process's waited-
                     for  children  have  been scheduled in user mode.
                     (See also times(2).)

Right?

(In fs/proc/array.c, those are the two lines from

                cputime_to_clock_t(utime),
                cputime_to_clock_t(cutime),
)

Cheers,

Michael

Re: /proc 2.6.24 changes for guest CPU accounting

[AP]

On Mon, Jun 23, 2008 at 12:51:11PM +0200, Michael Kerrisk wrote:
> > You must also notes that "user time" includes "guest time", if you want
> > real "user time" you must subtract "guest time".
> > The "guest time" is included in "user time" to not loose it when the
> > "reader" is not aware of the "guest time".
> 
> Hi Laurent (and Christian)
> 
> So, I just want to confirm.  You are saying that guest_time and
> cguest_time are respectively also included in the following fields
> 
>               utime %lu
...
>               cutime %ld
...
> Right?

If this function in ./kernel/sched.c is anything to go by and I'm not
being a complete noob, yes:

/*
 * Account guest cpu time to a process.
 * @p: the process that the cpu time gets accounted to
 * @cputime: the cpu time spent in virtual machine since the last update
 */
static void account_guest_time(struct task_struct *p, cputime_t cputime)
{
        cputime64_t tmp;
        struct cpu_usage_stat *cpustat = &kstat_this_cpu.cpustat;

        tmp = cputime_to_cputime64(cputime);

        p->utime = cputime_add(p->utime, cputime);
        p->gtime = cputime_add(p->gtime, cputime);

        cpustat->user = cputime64_add(cpustat->user, tmp);
        cpustat->guest = cputime64_add(cpustat->guest, tmp);
}

As such, I'll follow up with a new version of my previous patch.

AP

[PATCH] Documentation: add descs for guest fields in stat procfs files

[AP]

Git patch 5e84cfde51cf303d368fcb48f22059f37b3872de introduced a new
field to /proc/stat that represents guest (virtual cpu) time.

Git patch 9ac52315d4cf5f561f36dabaf0720c00d3553162 introduced the same
to /proc/<pid>/stat along with a guest time of the tasks children.

The patch below adds descriptions of these fields to the procfs
documentation included in the kernel.

Signed-Off-By: Andrew P <ap@zip.com.au>

diff -aur linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt
--- linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt	2008-06-23 22:27:13.000000000 +1000
+++ linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt	2008-06-24 22:16:53.000000000 +1000
@@ -210,9 +210,9 @@
   cmin_flt      number of minor faults with child's
   maj_flt       number of major faults
   cmaj_flt      number of major faults with child's
-  utime         user mode jiffies
+  utime         user mode jiffies (including gtime below*)
   stime         kernel mode jiffies
-  cutime        user mode jiffies with child's
+  cutime        user mode jiffies with child's (including cgtime below*)
   cstime        kernel mode jiffies with child's
   priority      priority level
   nice          nice level
@@ -239,6 +239,11 @@
   rt_priority   realtime priority
   policy        scheduling policy (man sched_setscheduler)
   blkio_ticks   time spent waiting for block IO
+  gtime         guest (virtual CPU) CPU time in jiffies
+  cgtime        guests' children's CPU time in jiffies
+
+* gtime and cgtime are included in these values so that applications that are
+  not aware of these fields do not lose time in their calculations.
 ..............................................................................
 
 
@@ -828,9 +833,9 @@
 since the system first booted.  For a quick look, simply cat the file:
 
   > cat /proc/stat
-  cpu  2255 34 2290 22625563 6290 127 456 0
-  cpu0 1132 34 1441 11311718 3675 127 438 0
-  cpu1 1123 0 849 11313845 2614 0 18 0
+  cpu  2255 34 2290 22625563 6290 127 456 0 0
+  cpu0 1132 34 1441 11311718 3675 127 438 0 0
+  cpu1 1123 0 849 11313845 2614 0 18 0 0
   intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...]
   ctxt 1990473
   btime 1062191376
@@ -843,7 +848,8 @@
 different kinds of work.  Time units are in USER_HZ (typically hundredths of a
 second).  The meanings of the columns are as follows, from left to right:
 
-- user: normal processes executing in user mode
+- user: normal processes executing in user mode (includes guest time below so
+        that guest-unaware applications do not lose time)
 - nice: niced processes executing in user mode
 - system: processes executing in kernel mode
 - idle: twiddling thumbs
@@ -851,6 +857,7 @@
 - irq: servicing interrupts
 - softirq: servicing softirqs
 - steal: involuntary wait
+- guest: time used to run a virtual CPU
 
 The "intr" line gives counts of interrupts  serviced since boot time, for each
 of the  possible system interrupts.   The first  column  is the  total of  all

Re: [PATCH] Documentation: add descs for guest fields in stat procfs files

[Laurent Vivier]

Le mardi 24 juin 2008 à 22:43 +1000, AP a écrit :
> Git patch 5e84cfde51cf303d368fcb48f22059f37b3872de introduced a new
> field to /proc/stat that represents guest (virtual cpu) time.
> 
> Git patch 9ac52315d4cf5f561f36dabaf0720c00d3553162 introduced the same
> to /proc/<pid>/stat along with a guest time of the tasks children.
> 
> The patch below adds descriptions of these fields to the procfs
> documentation included in the kernel.
> 
> Signed-Off-By: Andrew P <ap@zip.com.au>

It looks good to me.

Laurent

> diff -aur linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt
> --- linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt	2008-06-23 22:27:13.000000000 +1000
> +++ linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt	2008-06-24 22:16:53.000000000 +1000
> @@ -210,9 +210,9 @@
>    cmin_flt      number of minor faults with child's
>    maj_flt       number of major faults
>    cmaj_flt      number of major faults with child's
> -  utime         user mode jiffies
> +  utime         user mode jiffies (including gtime below*)
>    stime         kernel mode jiffies
> -  cutime        user mode jiffies with child's
> +  cutime        user mode jiffies with child's (including cgtime below*)
>    cstime        kernel mode jiffies with child's
>    priority      priority level
>    nice          nice level
> @@ -239,6 +239,11 @@
>    rt_priority   realtime priority
>    policy        scheduling policy (man sched_setscheduler)
>    blkio_ticks   time spent waiting for block IO
> +  gtime         guest (virtual CPU) CPU time in jiffies
> +  cgtime        guests' children's CPU time in jiffies
> +
> +* gtime and cgtime are included in these values so that applications that are
> +  not aware of these fields do not lose time in their calculations.
>  ..............................................................................
>  
> 
> @@ -828,9 +833,9 @@
>  since the system first booted.  For a quick look, simply cat the file:
>  
>    > cat /proc/stat
> -  cpu  2255 34 2290 22625563 6290 127 456 0
> -  cpu0 1132 34 1441 11311718 3675 127 438 0
> -  cpu1 1123 0 849 11313845 2614 0 18 0
> +  cpu  2255 34 2290 22625563 6290 127 456 0 0
> +  cpu0 1132 34 1441 11311718 3675 127 438 0 0
> +  cpu1 1123 0 849 11313845 2614 0 18 0 0
>    intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...]
>    ctxt 1990473
>    btime 1062191376
> @@ -843,7 +848,8 @@
>  different kinds of work.  Time units are in USER_HZ (typically hundredths of a
>  second).  The meanings of the columns are as follows, from left to right:
>  
> -- user: normal processes executing in user mode
> +- user: normal processes executing in user mode (includes guest time below so
> +        that guest-unaware applications do not lose time)
>  - nice: niced processes executing in user mode
>  - system: processes executing in kernel mode
>  - idle: twiddling thumbs
> @@ -851,6 +857,7 @@
>  - irq: servicing interrupts
>  - softirq: servicing softirqs
>  - steal: involuntary wait
> +- guest: time used to run a virtual CPU
>  
>  The "intr" line gives counts of interrupts  serviced since boot time, for each
>  of the  possible system interrupts.   The first  column  is the  total of  all
> 
-- 
------------- Laurent.Vivier@bull.net ---------------
"The best way to predict the future is to invent it."
- Alan Kay

Re: [PATCH] Documentation: add descs for guest fields in stat procfs files

[Michael Kerrisk]

On Tue, Jun 24, 2008 at 2:43 PM, AP <ap@zip.com.au> wrote:
> Git patch 5e84cfde51cf303d368fcb48f22059f37b3872de introduced a new
> field to /proc/stat that represents guest (virtual cpu) time.
>
> Git patch 9ac52315d4cf5f561f36dabaf0720c00d3553162 introduced the same
> to /proc/<pid>/stat along with a guest time of the tasks children.
>
> The patch below adds descriptions of these fields to the procfs
> documentation included in the kernel.
>
> Signed-Off-By: Andrew P <ap@zip.com.au>
>
> diff -aur linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt
> --- linux-2.6.26-rc7-git2.orig/Documentation/filesystems/proc.txt       2008-06-23 22:27:13.000000000 +1000
> +++ linux-2.6.26-rc7-git2/Documentation/filesystems/proc.txt    2008-06-24 22:16:53.000000000 +1000
> @@ -210,9 +210,9 @@
>   cmin_flt      number of minor faults with child's
>   maj_flt       number of major faults
>   cmaj_flt      number of major faults with child's
> -  utime         user mode jiffies
> +  utime         user mode jiffies (including gtime below*)
>   stime         kernel mode jiffies
> -  cutime        user mode jiffies with child's
> +  cutime        user mode jiffies with child's (including cgtime below*)
>   cstime        kernel mode jiffies with child's
>   priority      priority level
>   nice          nice level
> @@ -239,6 +239,11 @@
>   rt_priority   realtime priority
>   policy        scheduling policy (man sched_setscheduler)
>   blkio_ticks   time spent waiting for block IO
> +  gtime         guest (virtual CPU) CPU time in jiffies
> +  cgtime        guests' children's CPU time in jiffies
> +
> +* gtime and cgtime are included in these values so that applications that are
> +  not aware of these fields do not lose time in their calculations.
>  ..............................................................................
>
>
> @@ -828,9 +833,9 @@
>  since the system first booted.  For a quick look, simply cat the file:
>
>   > cat /proc/stat
> -  cpu  2255 34 2290 22625563 6290 127 456 0
> -  cpu0 1132 34 1441 11311718 3675 127 438 0
> -  cpu1 1123 0 849 11313845 2614 0 18 0
> +  cpu  2255 34 2290 22625563 6290 127 456 0 0
> +  cpu0 1132 34 1441 11311718 3675 127 438 0 0
> +  cpu1 1123 0 849 11313845 2614 0 18 0 0
>   intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...]
>   ctxt 1990473
>   btime 1062191376
> @@ -843,7 +848,8 @@
>  different kinds of work.  Time units are in USER_HZ (typically hundredths of a
>  second).  The meanings of the columns are as follows, from left to right:
>
> -- user: normal processes executing in user mode
> +- user: normal processes executing in user mode (includes guest time below so
> +        that guest-unaware applications do not lose time)
>  - nice: niced processes executing in user mode
>  - system: processes executing in kernel mode
>  - idle: twiddling thumbs
> @@ -851,6 +857,7 @@
>  - irq: servicing interrupts
>  - softirq: servicing softirqs
>  - steal: involuntary wait
> +- guest: time used to run a virtual CPU
>
>  The "intr" line gives counts of interrupts  serviced since boot time, for each
>  of the  possible system interrupts.   The first  column  is the  total of  all

Acked-by: Michael Kerrisk <mtk.manpages@gmail.com>