
[;1m  system_monitor()[0m

  Returns the current system monitoring settings set by [;;4m[0m
  [;;4merlang:system_monitor/2[0m as [;;4m{MonitorPid, Options}[0m, or [;;4mundefined[0m
  if no settings exist.

  The order of the options can be different from the one that was
  set.

[;1m  system_monitor(Arg)[0m

  When called with argument [;;4mundefined[0m, all system performance
  monitoring settings are cleared.

  Calling the function with [;;4m{MonitorPid, Options}[0m as argument is
  the same as calling [;;4merlang:system_monitor(MonitorPid, Options)[0m.

  Returns the previous system monitor settings just like [;;4m[0m
  [;;4merlang:system_monitor/0[0m.

[;1m  system_monitor(MonitorPid, Options)[0m

  Sets the system performance monitoring options. [;;4mMonitorPid[0m is a
  local process identifier (pid) receiving system monitor messages.

  The second argument is a list of monitoring options:

   • [;;4m{long_gc, Time}[0m - If a garbage collection in the system
     takes at least [;;4mTime[0m wall clock milliseconds, a message [;;4m[0m
     [;;4m{monitor, GcPid, long_gc, Info}[0m is sent to [;;4mMonitorPid[0m. [;;4m[0m
     [;;4mGcPid[0m is the pid that was garbage collected. [;;4mInfo[0m is a
     list of two-element tuples describing the result of the
     garbage collection.

     One of the tuples is [;;4m{timeout, GcTime}[0m, where [;;4mGcTime[0m is
     the time for the garbage collection in milliseconds. The
     other tuples are tagged with [;;4mheap_size[0m, [;;4mheap_block_size[0m, [;;4m[0m
     [;;4mstack_size[0m, [;;4mmbuf_size[0m, [;;4mold_heap_size[0m, and [;;4m[0m
     [;;4mold_heap_block_size[0m. These tuples are explained in the
     description of trace message [;;4mgc_minor_start[0m (see [;;4m[0m
     [;;4mtrace:process/4[0m). New tuples can be added, and the order of
     the tuples in the [;;4mInfo[0m list can be changed at any time
     without prior notice.

   • [;;4m{long_message_queue, {Disable, Enable}}[0m - If the message
     queue length of a process in the system reach [;;4mEnable[0m
     length, a [;;4mlong_message_queue[0m monitor message is sent to
     the process identified by [;;4mMonitorPid[0m. The monitor message
     will be on the form [;;4m{monitor, Pid, long_message_queue,[0m
     [;;4mLong}[0m, where [;;4mPid[0m is the process identifier of the process
     that got a long message queue and [;;4mLong[0m will equal [;;4mtrue[0m
     indicating that it is in a long message queue state. No
     more [;;4mlong_message_queue[0m monitor messages will be sent due
     to the process identified by [;;4mPid[0m until its message queue
     length falls down to a length of [;;4mDisable[0m length. When this
     happens, a [;;4mlong_message_queue[0m monitor message with [;;4mLong[0m
     equal to [;;4mfalse[0m will be sent to the process identified by [;;4m[0m
     [;;4mMonitorPid[0m indicating that the process is no longer in a 
     long message queue state. As of this, if the message queue
     length should again reach [;;4mEnable[0m length, a new [;;4m[0m
     [;;4mlong_message_queue[0m monitor message with [;;4mLong[0m set to [;;4mtrue[0m
     will again be sent. That is, a [;;4mlong_message_queue[0m monitor
     message is sent when a process enters or leaves a long
     message queue state where these state changes are defined
     by the [;;4mEnable[0m and [;;4mDisable[0m parameters.

     [;;4mEnable[0m length must be an integer larger than zero and [;;4m[0m
     [;;4mDisable[0m length must be an integer larger than or equal to
     zero. [;;4mDisable[0m length must also be smaller than [;;4mEnable[0m
     length. If the above is not satisfied the operation will
     fail with a [;;4mbadarg[0m error exception. You are recommended to
     use a much smaller value for [;;4mDisable[0m length than [;;4mEnable[0m
     length in order not to be flooded with [;;4mlong_message_queue[0m
     monitor messages.

   • [;;4m{long_schedule, Time}[0m - If a process or port in the system
     runs uninterrupted for at least [;;4mTime[0m wall clock
     milliseconds, a message [;;4m{monitor, PidOrPort, long_schedule,[0m
     [;;4mInfo}[0m is sent to [;;4mMonitorPid[0m. [;;4mPidOrPort[0m is the process
     or port that was running. [;;4mInfo[0m is a list of two-element
     tuples describing the event.

     If a [;;4mpid/0[0m, the tuples [;;4m{timeout, Millis}[0m, [;;4m{in,[0m
     [;;4mLocation}[0m, and [;;4m{out, Location}[0m are present, where [;;4m[0m
     [;;4mLocation[0m is either an MFA ([;;4m{Module, Function, Arity}[0m)
     describing the function where the process was scheduled
     in/out, or the atom [;;4mundefined[0m.

     If a [;;4mport/0[0m, the tuples [;;4m{timeout, Millis}[0m and [;;4m[0m
     [;;4m{port_op,Op}[0m are present. [;;4mOp[0m is one of [;;4mproc_sig[0m, [;;4m[0m
     [;;4mtimeout[0m, [;;4minput[0m, [;;4moutput[0m, [;;4mevent[0m, or [;;4mdist_cmd[0m,
     depending on which driver callback was executing.

     [;;4mproc_sig[0m is an internal operation and is never to appear,
     while the others represent the corresponding driver
     callbacks [;;4mtimeout[0m, [;;4mready_input[0m, [;;4mready_output[0m, [;;4mevent[0m,
     and [;;4moutputv[0m (when the port is used by distribution). Value [;;4m[0m
     [;;4mMillis[0m in tuple [;;4mtimeout[0m informs about the uninterrupted
     execution time of the process or port, which always is equal
     to or higher than the [;;4mTime[0m value supplied when starting
     the trace. New tuples can be added to the [;;4mInfo[0m list in a
     future release. The order of the tuples in the list can be
     changed at any time without prior notice.

     This can be used to detect problems with NIFs or drivers
     that take too long to execute. 1 ms is considered a good
     maximum time for a driver callback or a NIF. However, a
     time-sharing system is usually to consider everything < 100
     ms as "possible" and fairly "normal". However, longer
     schedule times can indicate swapping or a misbehaving
     NIF/driver. Misbehaving NIFs and drivers can cause bad
     resource utilization and bad overall system performance.

   • [;;4m{large_heap, Size}[0m - If a garbage collection in the system
     results in the allocated size of a heap being at least [;;4mSize[0m
     words, a message [;;4m{monitor, GcPid, large_heap, Info}[0m is
     sent to [;;4mMonitorPid[0m. [;;4mGcPid[0m and [;;4mInfo[0m are the same as for [;;4m[0m
     [;;4mlong_gc[0m earlier, except that the tuple tagged with [;;4mtimeout[0m
     is not present.

     The monitor message is sent if the sum of the sizes of all
     memory blocks allocated for all heap generations after a
     garbage collection is equal to or higher than [;;4mSize[0m.

     When a process is killed by [;;4mmax_heap_size[0m, it is killed
     before the garbage collection is complete and thus no large
     heap message is sent.

   • [;;4mbusy_port[0m - If a process in the system gets suspended
     because it sends to a busy port, a message [;;4m{monitor,[0m
     [;;4mSusPid, busy_port, Port}[0m is sent to [;;4mMonitorPid[0m. [;;4mSusPid[0m
     is the pid that got suspended when sending to [;;4mPort[0m.

   • [;;4mbusy_dist_port[0m If a process in the system gets suspended
     because it sends to a process on a remote node whose
     inter-node communication was handled by a busy port, a
     message [;;4m{monitor, SusPid, busy_dist_port, Port}[0m is sent to [;;4m[0m
     [;;4mMonitorPid[0m. [;;4mSusPid[0m is the pid that got suspended when
     sending through the inter-node communication port [;;4mPort[0m.

  Returns the previous system monitor settings just like [;;4m[0m
  [;;4merlang:system_monitor/0[0m.

  The arguments to [;;4msystem_monitor/2[0m specifies how all system
  monitoring on the node should be done, not how it should be
  changed. This means only one process at a time ([;;4mMonitorPid[0m) can
  be the receiver of system monitor messages. Also, the way to clear
  a specific monitor option is to not include it in the list [;;4m[0m
  [;;4mOptions[0m. All system monitoring will, however, be cleared if the
  process identified by [;;4mMonitorPid[0m terminates.

  There are no special option values (like zero) to clear an option.
  Some of the options have a unspecified minimum value. Lower values
  will be adjusted to the minimum value. For example, it is
  currently not possible to monitor all garbage collections with [;;4m[0m
  [;;4m{long_gc, 0}[0m.

  [;;4mNote[0m

    If a monitoring process gets so large that it itself starts to
    cause system monitor messages when garbage collecting, the
    messages enlarge the process message queue and probably make
    the problem worse. Keep the monitoring process neat and do not
    set the system monitor limits too tight.

  Failures:

   • [;;4mbadarg[0m - If [;;4mMonitorPid[0m does not exist.

   • [;;4mbadarg[0m - If [;;4mMonitorPid[0m is not a local process.
