
  -spec erlang:trace(PidPortSpec, How, FlagList) -> integer()
                        when
                            PidPortSpec ::
                                pid() |
                                port() |
                                all | processes | ports | existing |
                                existing_processes | existing_ports |
                                new | new_processes | new_ports,
                            How :: boolean(),
                            FlagList :: [trace_flag()].

  Types:
    -type trace_flag() ::
          all | send | 'receive' | procs | ports | call | arity |
          return_to | silent | running | exiting | running_procs |
          running_ports | garbage_collection | timestamp |
          cpu_timestamp | monotonic_timestamp |
          strict_monotonic_timestamp | set_on_spawn |
          set_on_first_spawn | set_on_link | set_on_first_link |
          {tracer, pid() | port()} |
          {tracer, module(), term()}.

  Turns on (if How == true) or off (if How == false) the trace
  flags in FlagList for the process or processes represented by 
  PidPortSpec.

  PidPortSpec is either a process identifier (pid) for a local
  process, a port identifier, or one of the following atoms:

  all:
    All currently existing processes and ports and all that will
    be created in the future.

  processes:
    All currently existing processes and all that will be created
    in the future.

  ports:
    All currently existing ports and all that will be created in
    the future.

  existing:
    All currently existing processes and ports.

  existing_processes:
    All currently existing processes.

  existing_ports:
    All currently existing ports.

  new:
    All processes and ports that will be created in the future.

  new_processes:
    All processes that will be created in the future.

  new_ports:
    All ports that will be created in the future.

  FlagList can contain any number of the following flags (the
  "message tags" refers to the list of trace messages):

  all:
    Sets all trace flags except tracer and cpu_timestamp,
    which are in their nature different than the others.

  send:
    Traces sending of messages.

    Message tags: send and send_to_non_existing_process.

  'receive':
    Traces receiving of messages.

    Message tags: 'receive'.

  call:
    Traces certain function calls. Specify which function calls to
    trace by calling erlang:trace_pattern/3.

    Message tags: call and return_from.

  silent:
    Used with the call trace flag. The call, return_from,
    and return_to trace messages are inhibited if this flag is
    set, but they are executed as normal if there are match
    specifications.

    Silent mode is inhibited by executing erlang:trace(_, false,
    [silent|_]), or by a match specification executing the
    function {silent, false}.

    The silent trace flag facilitates setting up a trace on many
    or even all processes in the system. The trace can then be
    activated and deactivated using the match specification
    function {silent,Bool}, giving a high degree of control of
    which functions with which arguments that trigger the trace.

    Message tags: call, return_from, and return_to. Or
    rather, the absence of.

  return_to:
    Used with the call trace flag. Traces the return from a
    traced function back to its caller. Only works for functions
    traced with option local to erlang:trace_pattern/3.

    The semantics is that a trace message is sent when a call
    traced function returns, that is, when a chain of tail
    recursive calls ends. Only one trace message is sent per chain
    of tail recursive calls, so the properties of tail
    recursiveness for function calls are kept while tracing with
    this flag. Using call and return_to trace together makes
    it possible to know exactly in which function a process
    executes at any time.

    To get trace messages containing return values from functions,
    use the {return_trace} match specification action instead.

    Message tags: return_to.

  procs:
    Traces process-related events.

    Message tags: spawn, spawned, exit, register, 
    unregister, link, unlink, getting_linked, and 
    getting_unlinked.

  ports:
    Traces port-related events.

    Message tags: open, closed, register, unregister, 
    getting_linked, and getting_unlinked.

  running:
    Traces scheduling of processes.

    Message tags: in and out.

  exiting:
    Traces scheduling of exiting processes.

    Message tags: in_exiting, out_exiting, and out_exited.

  running_procs:
    Traces scheduling of processes just like running. However,
    this option also includes schedule events when the process
    executes within the context of a port without being scheduled
    out itself.

    Message tags: in and out.

  running_ports:
    Traces scheduling of ports.

    Message tags: in and out.

  garbage_collection:
    Traces garbage collections of processes.

    Message tags: gc_minor_start, gc_max_heap_size, and 
    gc_minor_end.

  timestamp:
    Includes a time stamp in all trace messages. The time stamp
    (Ts) has the same form as returned by erlang:now().

  cpu_timestamp:
    A global trace flag for the Erlang node that makes all trace
    time stamps using flag timestamp to be in CPU time, not wall
    clock time. That is, cpu_timestamp is not be used if 
    monotonic_timestamp or strict_monotonic_timestamp is
    enabled. Only allowed with PidPortSpec==all. If the host
    machine OS does not support high-resolution CPU time
    measurements, trace/3 exits with badarg. Notice that most
    OS do not synchronize this value across cores, so be prepared
    that time can seem to go backwards when using this option.

  monotonic_timestamp:
    Includes an Erlang monotonic time time stamp in all trace
    messages. The time stamp (Ts) has the same format and value as
    produced by erlang:monotonic_time(nanosecond). This flag
    overrides flag cpu_timestamp.

  strict_monotonic_timestamp:
    Includes an time stamp consisting of Erlang monotonic time
    and a monotonically increasing integer in all trace messages.
    The time stamp (Ts) has the same format and value as produced
    by { erlang:monotonic_time(nanosecond), 
    erlang:unique_integer([monotonic])}. This flag overrides
    flag cpu_timestamp.

  arity:
    Used with the call trace flag. {M, F, Arity} is specified
    instead of {M, F, Args} in call trace messages.

  set_on_spawn:
    Makes any process created by a traced process inherit its
    trace flags, including flag set_on_spawn.

  set_on_first_spawn:
    Makes the first process created by a traced process inherit
    its trace flags, excluding flag set_on_first_spawn.

  set_on_link:
    Makes any process linked by a traced process inherit its trace
    flags, including flag set_on_link.

  set_on_first_link:
    Makes the first process linked to by a traced process inherit
    its trace flags, excluding flag set_on_first_link.

  {tracer, Tracer}:
    Specifies where to send the trace messages. Tracer must be
    the process identifier of a local process or the port
    identifier of a local port.

  {tracer, TracerModule, TracerState}:
    Specifies that a tracer module is to be called instead of
    sending a trace message. The tracer module can then ignore or
    change the trace message. For more details on how to write a
    tracer module, see erl_tracer(3).

  If no tracer is specified, the calling process receives all the
  trace messages.

  The effect of combining set_on_first_link with set_on_link is
  the same as set_on_first_link alone. Likewise for set_on_spawn
  and set_on_first_spawn.

  The tracing process receives the trace messages described in the
  following list. Pid is the process identifier of the traced
  process in which the traced event has occurred. The third tuple
  element is the message tag.

  If flag timestamp, strict_monotonic_timestamp, or 
  monotonic_timestamp is specified, the first tuple element is 
  trace_ts instead, and the time stamp is added as an extra element
  last in the message tuple. If multiple time stamp flags are
  passed, timestamp has precedence over 
  strict_monotonic_timestamp, which in turn has precedence over 
  monotonic_timestamp. All time stamp flags are remembered, so if
  two are passed and the one with highest precedence later is
  disabled, the other one becomes active.

  If a match specification (applicable only for call, send and 
  'receive' tracing) contains a {message} action function with a
  non-boolean value, that value is added as an extra element to the
  message tuple either in the last position or before the timestamp
  (if it is present).

  Trace messages:

  {trace, PidPort, send, Msg, To}:
    When PidPort sends message Msg to process To.

  {trace, PidPort, send_to_non_existing_process, Msg, To}:
    When PidPort sends message Msg to the non-existing process 
    To.

  {trace, PidPort, 'receive', Msg}:
    When PidPort receives message Msg. If Msg is set to
    time-out, a receive statement can have timed out, or the
    process received a message with the payload timeout.

  {trace, Pid, call, {M, F, Args}}:
    When Pid calls a traced function. The return values of calls
    are never supplied, only the call and its arguments.

    Trace flag arity can be used to change the contents of this
    message, so that Arity is specified instead of Args.

  {trace, Pid, return_to, {M, F, Arity}}:
    When Pid returns to the specified function. This trace
    message is sent if both the flags call and return_to are
    set, and the function is set to be traced on local function
    calls. The message is only sent when returning from a chain of
    tail recursive function calls, where at least one call
    generated a call trace message (that is, the functions match
    specification matched, and {message, false} was not an
    action).

  {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
    When Pid returns from the specified function. This trace
    message is sent if flag call is set, and the function has a
    match specification with a return_trace or exception_trace
    action.

  {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
    When Pid exits from the specified function because of an
    exception. This trace message is sent if flag call is set,
    and the function has a match specification with an 
    exception_trace action.

  {trace, Pid, spawn, Pid2, {M, F, Args}}:
    When Pid spawns a new process Pid2 with the specified
    function call as entry point.

    Args is supposed to be the argument list, but can be any term
    if the spawn is erroneous.

  {trace, Pid, spawned, Pid2, {M, F, Args}}:
    When Pid is spawned by process Pid2 with the specified
    function call as entry point.

    Args is supposed to be the argument list, but can be any term
    if the spawn is erroneous.

  {trace, Pid, exit, Reason}:
    When Pid exits with reason Reason.

  {trace, PidPort, register, RegName}:
    When PidPort gets the name RegName registered.

  {trace, PidPort, unregister, RegName}:
    When PidPort gets the name RegName unregistered. This is
    done automatically when a registered process or port exits.

  {trace, Pid, link, Pid2}:
    When Pid links to a process Pid2.

  {trace, Pid, unlink, Pid2}:
    When Pid removes the link from a process Pid2.

  {trace, PidPort, getting_linked, Pid2}:
    When PidPort gets linked to a process Pid2.

  {trace, PidPort, getting_unlinked, Pid2}:
    When PidPort gets unlinked from a process Pid2.

  {trace, Port, open, Pid, Driver}:
    When Pid opens a new port Port with the running Driver.

    Driver is the name of the driver as an atom.

  {trace, Port, closed, Reason}:
    When Port closes with Reason.

  {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
    When Pid is scheduled to run. The process runs in function 
    {M, F, Arity}. On some rare occasions, the current function
    cannot be determined, then the last element is 0.

  {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} | 0}:
    When Pid is scheduled out. The process was running in
    function {M, F, Arity}. On some rare occasions, the current
    function cannot be determined, then the last element is 0.

  {trace, Port, in, Command | 0}:
    When Port is scheduled to run. Command is the first thing
    the port will execute, it can however run several commands
    before being scheduled out. On some rare occasions, the
    current function cannot be determined, then the last element
    is 0.

    The possible commands are call, close, command, connect, 
    control, flush, info, link, open, and unlink.

  {trace, Port, out, Command | 0}:
    When Port is scheduled out. The last command run was 
    Command. On some rare occasions, the current function cannot
    be determined, then the last element is 0. Command can
    contain the same commands as in

  {trace, Pid, gc_minor_start, Info}:
    Sent when a young garbage collection is about to be started. 
    Info is a list of two-element tuples, where the first element
    is a key, and the second is the value. Do not depend on any
    order of the tuples. The following keys are defined:

    heap_size:
      The size of the used part of the heap.

    heap_block_size:
      The size of the memory block used for storing the heap and
      the stack.

    old_heap_size:
      The size of the used part of the old heap.

    old_heap_block_size:
      The size of the memory block used for storing the old
      heap.

    stack_size:
      The size of the stack.

    recent_size:
      The size of the data that survived the previous garbage
      collection.

    mbuf_size:
      The combined size of message buffers associated with the
      process.

    bin_vheap_size:
      The total size of unique off-heap binaries referenced from
      the process heap.

    bin_vheap_block_size:
      The total size of binaries allowed in the virtual heap in
      the process before doing a garbage collection.

    bin_old_vheap_size:
      The total size of unique off-heap binaries referenced from
      the process old heap.

    bin_old_vheap_block_size:
      The total size of binaries allowed in the virtual old heap
      in the process before doing a garbage collection.

    wordsize:
      For the gc_minor_start event it is the size of the need
      that triggered the GC. For the corresponding gc_minor_end
      event it is the size of reclaimed memory = start 
      heap_size - end heap_size.

    All sizes are in words.

  {trace, Pid, gc_max_heap_size, Info}:
    Sent when the max_heap_size is reached during garbage
    collection. Info contains the same kind of list as in
    message gc_start, but the sizes reflect the sizes that
    triggered max_heap_size to be reached.

  {trace, Pid, gc_minor_end, Info}:
    Sent when young garbage collection is finished. Info
    contains the same kind of list as in message gc_minor_start,
    but the sizes reflect the new sizes after garbage collection.

  {trace, Pid, gc_major_start, Info}:
    Sent when fullsweep garbage collection is about to be started. 
    Info contains the same kind of list as in message 
    gc_minor_start.

  {trace, Pid, gc_major_end, Info}:
    Sent when fullsweep garbage collection is finished. Info
    contains the same kind of list as in message gc_minor_start,
    but the sizes reflect the new sizes after a fullsweep garbage
    collection.

  If the tracing process/port dies or the tracer module returns 
  remove, the flags are silently removed.

  Each process can only be traced by one tracer. Therefore, attempts
  to trace an already traced process fail.

  Returns a number indicating the number of processes that matched 
  PidPortSpec. If PidPortSpec is a process identifier, the return
  value is 1. If PidPortSpec is all or existing, the return
  value is the number of processes running. If PidPortSpec is new,
  the return value is 0.

  Failure: badarg if the specified arguments are not supported.
  For example, cpu_timestamp is not supported on all platforms.
