sys/man/4/iostats

   1 .TH IOSTATS 4
   2 .SH NAME
   3 iostats \- file system to measure I/O
   4 .SH SYNOPSIS
   5 .B iostats
   6 [
   7 .B -d
   8 ] [
   9 .B -C
  10 ] [
  11 .B -f
  12 .I dbfile
  13 ]
  14 .I cmd
  15 [
  16 .I args...
  17 ]
  18 .SH DESCRIPTION
  19 .I Iostats
  20 is a user-level 9p filter that interposes itself between a program
  21 and the regular file server, which
  22 allows it to gather statistics of file system
  23 use at the level of the Plan 9 file system protocol, 9P.
  24 After a program
  25 exits a report is printed on standard error.
  26 .PP
  27 The report consists of three sections.
  28 The first section reports the amount
  29 of user data in
  30 .B read
  31 and
  32 .B write
  33 messages sent by the program and the average rate at
  34 which the data was transferred.
  35 The
  36 .B protocol
  37 line reports the amount
  38 of data sent as message headers, that is,
  39 protocol overhead.
  40 The
  41 .B rpc
  42 line reports the
  43 total number of file system transactions.
  44 .PP
  45 The second section gives
  46 the number of messages, the fastest, slowest, and average turn around
  47 time and the amount of data involved with each 9P
  48 message type.
  49 The final section gives an I/O summary for each file used
  50 by the program in terms of opens, reads and writes.
  51 .PP
  52 If the
  53 .B -d
  54 flag is present, a debugging log including all traffic
  55 is written to
  56 .I dbfile
  57 (default
  58 .BR iostats.out ).
  59 .PP
  60 The
  61 .B -C
  62 flag sets the MCACHE flag on the mount which allows
  63 the kernel to cache (see
  64 .IR bind (1)).
  65 .SH EXAMPLE
  66 Display summary of file I/O incurred by
  67 .IR ls (1):
  68 .IP
  69 .EX
  70 iostats ls
  71 .EE
  72 .PP
  73 Start a new shell, displaying all 9P traffic caused by the shell or its children:
  74 .IP
  75 .EX
  76 iostats -df /fd/1 rc
  77 .EE
  78 .SH SOURCE
  79 .B /sys/src/cmd/iostats.c
  80 .SH SEE ALSO
  81 .IR dup (3),
  82 .IR exportfs (4)
  83 .SH BUGS
  84 Poor clock resolution means that large amounts of I/O must be done to
  85 get accurate rate figures.
  86 .PP
  87 Can be fooled by programs that do fresh mounts outside its purview,
  88 or by the use of names of files with content that can vary by process (e.g.,
  89 .LR #d ,
  90 .LR /dev/cons ).