## 4.41 Obtaining Runtime Statistics

The predicate statistics/2 is built-in. More high level predicates are available from library `library(statistics)`. See section A.51.

statistics(+Key, -Value)
  Unify system statistics determined by Key with Value. The possible keys are given in the table 6. This predicate supports additional keys for compatibility reasons. These keys are described in table 7. CPU time results are based on clock_gettime(), times() or wall time since the process was started (in that order of preference). On Windows GetProcessTimes() is used. Both clock_gettime() and GetProcessTimes() provide a nanosecond resolution interface. The actual resolution depends on the platform.

  Starting with version 9.1.9, the `cputime` and `inferences` keys include the final value for threads that have been created by the calling thread and has been joined by the calling thread. The new keys `self_cputime` and `self_inferences` may be used to get statistics for the calling thread only. Both keys also exist in the single threaded version, where the “self'' key always returns the same value as the onle without “self''.

  Native keys (times as float in seconds)
  agc | Number of atom garbage collections performed
  agc_gained | Number of atoms removed
  agc_time | Time spent in atom garbage collections
  atoms | Total number of defined atoms
  atom_space | Bytes used to represent atoms
  c_stack | System (C-) stack limit. 0 if not known.
  cgc | Number of clause garbage collections performed
  cgc_gained | Number of clauses reclaimed
  cgc_time | Time spent in clause garbage collections
  clauses | Total number of clauses in the program
  codes | Total size of (virtual) executable code in words
  cputime | (User) CPU time since thread was started in seconds. Includes CPU time in completed child threads. See also `self_cputime` and `process_cputime`.
  epoch | Time stamp when thread was started
  errors | Number of error mesages printed
  functors | Total number of defined name/arity pairs
  functor_space | Bytes used to represent functors
  global | Allocated size of the global stack in bytes
  globalused | Number of bytes in use on the global stack
  globallimit | Size to which the global stack is allowed to grow
  global_shifts | Number of global stack expansions
  heapused | Bytes of heap in use by Prolog (0 if not maintained)
  inferences | Total number of passes via the call and redo ports since Prolog was started. Includes inferences in child threads. See also `self_inferences`.
  modules | Total number of defined modules
  local | Allocated size of the local stack in bytes
  local_shifts | Number of local stack expansions
  locallimit | Size to which the local stack is allowed to grow
  localused | Number of bytes in use on the local stack
  table_space_used | Amount of bytes in use by the thread's answer tables
  trail | Allocated size of the trail stack in bytes
  trail_shifts | Number of trail stack expansions
  traillimit | Size to which the trail stack is allowed to grow
  trailused | Number of bytes in use on the trail stack
  shift_time | Time spent in stack-shifts
  self_cputime | (User) CPU time since thread was started in seconds
  self_inferences | Total number of passes via the call and redo ports since Prolog was started
  stack | Total memory in use for stacks in all threads
  predicates | Total number of predicates. This includes predicates that are undefined or not yet resolved.
  indexes_created | Number of clause index tables creates.
  indexes_destroyed | Number of clause index tables destroyed.
  process_epoch | Time stamp when Prolog was started
  process_cputime | (User) CPU time since Prolog was started in seconds
  thread_cputime | MT-version: Seconds CPU time used by finished threads. The implementation requires non-portable functionality. Currently works on Linux, MacOSX, Windows and probably some more.
  threads | MT-version: number of active threads
  threads_created | MT-version: number of created threads
  engines | MT-version: number of existing engines
  engines_created | MT-version: number of created engines
  threads_peak | MT-version: highest id handed out. This is a fair but possibly not 100% accurate value for the highest number of threads since the process was created.
  warnings | Number of warning mesages printed

  Table 6 : Keys for statistics/2. Space is expressed in bytes. Time is expressed in seconds, represented as a floating point number.

  Compatibility keys (times in milliseconds)
  runtime | [ CPU time, CPU time since last ] (milliseconds, excluding time spent in garbage collection)
  system_time | [ System CPU time, System CPU time since last ] (milliseconds)
  real_time | [ Wall time, Wall time since last ] (integer seconds. See get_time/1)
  walltime | [ Wall time since start, Wall time since last] (milliseconds, SICStus compatibility)
  memory | [ Total unshared data, free memory ] (Used is based on `ru_idrss` from getrusage(). Free is based on `RLIMIT_DATA` from getrlimit(). Both are reported as zero if the OS lacks support. Free is -1 if getrlimit() is supported but returns infinity.)
  stacks | [ global use, local use ]
  program | [ heap use, 0 ]
  global_stack | [ global use, global free ]
  local_stack | [ local use, local free ]
  trail | [ trail use, trail free ]
  garbage_collection | [ number of GC, bytes gained, time spent, bytes left ] The last column is a SWI-Prolog extension. It contains the sum of the memory left after each collection, which can be divided by the count to find the average working set size after GC. Use `[Count, Gained, Time|_]` for compatibility.
  stack_shifts | [ global shifts, local shifts, time spent ]
  atoms | [ number, memory use, 0 ]
  atom_garbage_collection | [ number of AGC, bytes gained, time spent ]
  clause_garbage_collection | [ number of CGC, clauses gained, time spent ]
  core | Same as memory

  Table 7 : Compatibility keys for statistics/2. Time is expressed in milliseconds.