hphp/doc/hhprof

   1 HHVM's HHProf feature provides memory heap profiling based on optional jemalloc
   2 functionality.  For HHProf to function, jemalloc must be built with
   3 --enable-prof, and HHVM must be built with USE_JEMALLOC and ENABLE_HHPROF.
   4
   5 HHProf configuration is controlled in part by the following boolean runtime
   6 configuration options, all of which default to false:
   7
   8 * HHProf.Enabled: If true, enable admin server commands:
   9
  10   /hhprof/start:    start profiling
  11       requestType   "all" or "next"*
  12       url           profile next matching url for "next"
  13       lgSample      lg sample rate
  14       profileType   "current"* or "cumulative"
  15   /hhprof/status:   configuration and current dump status
  16   /hhprof/stop:     stop profiling
  17   /pprof/cmdline:   program command line
  18   /pprof/heap:      heap dump
  19   /pprof/symbol:    symbol lookup
  20       retain        regex for symbols client cares about
  21       exclude       regex for symbols client does not care about
  22
  23   The /hhprof/* endpoints are intended for direct use, whereas the /pprof/*
  24   endpoints support jeprof (included with jemalloc).
  25
  26 * HHProf.Active: If true, activate allocation sampling during startup.  This is
  27   useful if the usage goal is to gain an application-global understanding of
  28   memory usage; for request-based profiling, activation/deactivation is
  29   controlled via other means.
  30
  31 * HHProf.Accum: If true, enable cumulative sample statistics in addition to
  32   current sample statistics.  Beware that metadata overhead is proportional to
  33   the number of unique backtraces associated with sampled allocations, and with
  34   cumulative statistics enabled, no samples are ever discarded.  This means that
  35   if the application's call graph is complex, a combinatorial explosion of
  36   potential backtraces can cause unbounded metadata growth.
  37
  38 * HHProf.Request: If true, enable support for per request profiling.  This
  39   causes selected requests to allocate memory such that PHP-level allocations
  40   are independently allocated, thus making their effects visible in heap
  41   profiles.
  42
  43 Following are some common use case examples:
  44
  45 * Per request profiling
  46
  47   Start hhvm as such:
  48
  49     hhvm -m server -vHHProf.Enabled=true -vHHProf.Request=true
  50
  51   Profile the next request:
  52
  53     curl -s 'example.com:8088/hhprof/start?requestType=next&lgSample=12'
  54
  55   Profile the next request to a particular endpoint:
  56
  57     curl -s 'example.com:8088/hhprof/start?requestType=next&url=home.php&lgSample=12'
  58
  59   Note that the default sample rate (on average once per 512 KiB) is too low to
  60   capture meaningful sample sets unless the allocation volume is sufficiently
  61   high.  Therefore the above examples set the rate to average one sample per 4
  62   KiB, which is a reasonable setting for most purposes, though the higher the
  63   sample rate, the higher the computational and memory overhead.
  64
  65   Download the resulting profile using jeprof, symbolizing only PHP functions:
  66
  67     jeprof --raw --retain='^PHP::' 'example.com:8088/pprof/heap' > hhprof.raw
  68
  69   Generate a call graph, focusing only on PHP functions:
  70
  71     jeprof --pdf --retain='^PHP::' hhprof.raw > hhprof.pdf
  72
  73 * Whole server profiling
  74
  75   Start hhvm as such:
  76
  77     hhvm -m server -vHHProf.Enabled=true -vHHProf.Active=true
  78
  79   Download a profile for currently allocated memory:
  80
  81     jeprof --raw 'example.com:8088/pprof/heap' > hhprof.raw
  82
  83   Generate a call graph:
  84
  85     jeprof --pdf hhprof.raw > hhprof.pdf