msa/msa.1

   1 .Dd 3/7/14
   2 .Dt msa 1
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm msa
   6 .Nd Mach spy agency. Shows mach ipc, vouchers, importance boosts, etc.
   7 .Sh SYNOPSIS             \" Section Header - required - don't modify
   8 .Nm
   9 .Op Fl ho
  10 .Op Fl -help
  11 .Op Fl -verbose
  12 .Op Fl -version
  13 .Op Fl -lifecycle Ar all | user | none
  14 .Op Fl -mach-msg Ar all | user | voucher | none
  15 .Op Fl -ouput Ar file
  16 .Op Fl -raw-timestamps
  17 .Op Fl -mach-absolute-time
  18 .Op Fl -event-index
  19 .Op Ar
  20 .Sh DESCRIPTION
  21 The
  22 .Nm
  23 command is used to observe voucher and importance propagation.
  24 .Nm
  25 displays mach message senders and receivers, message state (voucher, importance, reply expected, etc.) and receiver behavior such as refusing a voucher.
  26 .Nm
  27 shows process & thread lifecycle events, adoption & clearing of vouchers by threads, process importance count changes, and process DarwinBG state.
  28 .Nm
  29 uses the kernel trace facility and can be run live or against saved trace files.
  30 .Pp
  31 Options are as follows:
  32 .Pp
  33
  34 .Bl -tag -width -indent
  35 .It Fl h, -help
  36 Print help.
  37 .It Fl -verbose
  38 Print additional details and output.
  39 .It Fl -version
  40 Print version info.
  41 .It Fl -lifecycle Ar all | user | none
  42 Set the process and thread lifecycle filter level. The default is "user".
  43 .Bl -tag -width -indent
  44 .It all
  45 Show kernel & userspace process and thread events
  46 .It user
  47 Show userspace process and thread events
  48 .It none
  49 Show no process and thread events
  50 .El
  51 .It Fl -mach-msg Ar all | user | voucher | none
  52 Set the mach message sender/receiver filter level. The default is "voucher".
  53 .Bl -tag -width -indent
  54 .It all
  55 Show all mach message senders/receivers
  56 .It user
  57 Show mach message senders/receivers where both the sender and receiver are in userspace
  58 .It voucher
  59 Show "interesting" mach message senders/receivers. An "interesting" message is any message containing a voucher, any message not containing a voucher if the sending thread has adopted a voucher, and any message carrying importance.
  60 .It none
  61 Show no mach message senders/receivers
  62 .El
  63 .It Fl o, -output Ar file
  64 Write output to
  65 .Ar file
  66 .It Fl -raw-timestamps
  67 Do not show time as a delta from the first trace event, print the actual time offsets.
  68 .It Fl -mach-absolute-time
  69 Do not translate time from mach absolute units to nanoseconds.
  70 .It Fl -event-index
  71 Print the index of each event.
  72 .El
  73 .Sh OUTPUT
  74 .Nm
  75 displays columns of data, the first five columns are fixed. The data after the fifth column depends on the type of event. Example output below (your terminal will need to be at least 200 characters wide to display this correctly):
  76
  77         Time(uS)          Type      Thread     ThreadVoucher                   Process  ;;  Message-From/To                  MsgID        MsgVoucher   DeliveryTime  FLAGS
  78          9304.56          send         8C2                 -          coreaudiod (236)  ;;  -> coreaudiod (236)                  2                 -              -  ONEWAY
  79          9346.52       impdelv         8A6                 -          coreaudiod (236)  ;;  linked to coreaudiod (236)'s live importance chain
  80          9349.02          recv         8A6                 -          coreaudiod (236)  ;;  <- coreaudiod (236)                  2  5EBD6CB68FF6401F          44.46
  81          9361.50         adopt         8A6  5EBD6CB68FF6401F          coreaudiod (236)  ;;
  82
  83 .Bl -tag -width -indent
  84 .It The column headers have the following meanings:
  85 .Bl -tag -width -indent
  86 .It Time
  87 The Time column displays the number of microseconds elapsed since
  88 .Nm
  89 started, or since the first event in the trace file. This value may be modified by
  90 .Fl -raw-timestamps
  91 or
  92 .Fl -mach-absolute-time.
  93 You might set these flags in order to correlate timestamps with output from another process that was printing mach_absolute_time() based timestamps.
  94 .It Type
  95 This describes the type of event being reported. Information to the right of the ';;' will vary based on this type.
  96 .It Thread
  97 The Thread column shows the thread id of the thread that generated the event. This is the thread id as displayed by
  98 .Xr trace 1
  99 and
 100 .Xr kdprof 1
 101 and may be cross correlated with trace events shown by either. Note that in some cases a thread in process A may cause changes in process B, for example a thread in Safari might raise the importance of a daemon.
 102 .It ThreadVoucher
 103 The ThreadVoucher column shows the id of any voucher currently adopted by the thread. This voucher id is the same identifier as shown by
 104 .Xr lsmp 1 .
 105 A '-' means that
 106 .Nm
 107 has not yet seen a voucher adopt for the thread. A NULL voucher is displayed as '0'.
 108 .It Process
 109 The Process column shows the name and pid of the process executing. The name is limited to 16 characters and may appear truncated.
 110 .El
 111 .It Mach message send/recv have the following additional column headers:
 112 .Bl -tag -width -indent
 113 .It Message-From/To
 114 This field shows either the sender or the recipient of the message. The arrow at the beginning will indicate the direction the message is flowing. A '->' means sent to, a '<-' means received from. The name of the sender or recipient is limited to 16 characters and may appear truncated. Rarely, you may see '???' as the name, which means
 115 .Nm
 116 was unable to determine the source or destination of the message.
 117 .It MsgID
 118 The MsgID is a unique identifier for each mach message. A mach message has exactly one sender, and one receiver. However, a sending process may send several messages to a receiver before any are received. The MsgID allows disambiguation of exact message send and receipt time.
 119 .It MsgVoucher
 120 If this field is set, it shows the id of the voucher being carried by the mach message. Note that in some cases, the sender will show no voucher, but the receiver will have a voucher. This is the kernel providing a voucher for a process sending "old style" importance to a process that wants to receive vouchers.
 121 .It DeliveryTime
 122 This is the time it took to deliver the message, in uS. If the time cannot be calculated, it will show as '-'.
 123 .It FLAGS
 124 The FLAGS field will indicate various mach message behaviors:
 125 .Bl -tag -width -indent
 126 .It ONEWAY
 127 This message cannot be replied to
 128 .It MSGH_BITS_RAISED_IMPORTANCE
 129 This message carries "old style" importance
 130 .It VOUCHER-REFUSED
 131 The message carried a voucher, and the receiver refused to accept it
 132 .El
 133 .El
 134 .El
 135 .Sh EXAMPLES
 136 .Bl -tag -width -indent
 137 .It Here are several examples of usage:
 138 .Bl -tag -width -indent
 139 .It msa | grep BOOST
 140 This will show live boost/unboost behavior. Useful for watching what UI interactions will cause boosting.
 141 .It msa | grep -e APP-NAME -e DAEMON-NAME -e OTHER-DAEMON-NAME
 142 This will restrict output to only events dealing with an app and targetted daemons. This is useful to reduce the amount of data you need to watch.
 143 .It trace -L /tmp/temp.trace; msa /tmp/temp.trace
 144 This uses trace to capture a trace file for later analysis by msa.
 145 .El
 146 .El
 147 .Sh SEE ALSO
 148 .\" List links in ascending order by section, alphabetically within a section.
 149 .\" Please do not reference files that do not exist without filing a bug report
 150 .Xr kdprof 1 ,
 151 .Xr lsmp 1,
 152 .Xr trace 1
 153 .\" .Sh BUGS              \" Document known, unremedied bugs
 154 .\" .Sh HISTORY           \" Document history if command behaves in a unique manner