src/docs/user/field/darkconsole.diviner

   1 @title Using DarkConsole
   2 @group fieldmanual
   3
   4 Enabling and using the built-in debugging and performance console.
   5
   6 Overview
   7 ========
   8
   9 DarkConsole is a debugging console built into Phabricator which exposes
  10 configuration, performance and error information. It can help you detect,
  11 understand and resolve bugs and performance problems in Phabricator
  12 applications.
  13
  14
  15 Security Warning
  16 ================
  17
  18 WARNING: Because DarkConsole exposes some configuration and debugging
  19 information, it is disabled by default and you should be cautious about
  20 enabling it in production.
  21
  22 Particularly, DarkConsole may expose some information about your session
  23 details or other private material. It has some crude safeguards against this,
  24 but does not completely sanitize output.
  25
  26 This is mostly a risk if you take screenshots or copy/paste output and share
  27 it with others.
  28
  29
  30 Enabling DarkConsole
  31 ====================
  32
  33 You enable DarkConsole in your configuration, by setting `darkconsole.enabled`
  34 to `true`, and then turning it on in {nav Settings > Developer Settings}.
  35
  36 Once DarkConsole is enabled, you can show or hide it by pressing ##`## on your
  37 keyboard.
  38
  39 Since the setting is not available to logged-out users, you can also set
  40 `darkconsole.always-on` if you need to access DarkConsole on logged-out pages.
  41
  42 DarkConsole has a number of tabs, each of which is powered by a "plugin". You
  43 can use them to access different debugging and performance features.
  44
  45
  46 Plugin: Error Log
  47 =================
  48
  49 The "Error Log" plugin shows errors that occurred while generating the page,
  50 similar to the httpd `error.log`. You can send information to the error log
  51 explicitly with the @{function@libphutil:phlog} function.
  52
  53 If errors occurred, a red dot will appear on the plugin tab.
  54
  55
  56 Plugin: Request
  57 ===============
  58
  59 The "Request" plugin shows information about the HTTP request the server
  60 received, and the server itself.
  61
  62
  63 Plugin: Services
  64 ================
  65
  66 The "Services" plugin lists calls a page made to external services, like
  67 MySQL and subprocesses.
  68
  69 The Services tab can help you understand and debug issues related to page
  70 behavior: for example, you can use it to see exactly what queries or commands a
  71 page is running. In some cases, you can re-run those queries or commands
  72 yourself to examine their output and look for problems.
  73
  74 This tab can also be particularly useful in understanding page performance,
  75 because many performance problems are caused by inefficient queries (queries
  76 with bad query plans or which take too long) or repeated queries (queries which
  77 could be better structured or benefit from caching).
  78
  79 When analyzing performance problems, the major things to look for are:
  80
  81 **Summary**: In the summary table at the top of the tab, are any categories
  82 of events dominating the performance cost? For normal pages, the costs should
  83 be roughly along these lines:
  84
  85 | Event Type | Approximate Cost |
  86 |---|---|
  87 | Connect | 1%-10% |
  88 | Query | 10%-40% |
  89 | Cache | 1% |
  90 | Event | 1% |
  91 | Conduit | 0%-80% |
  92 | Exec | 0%-80% |
  93 | All Services | 10%-75% |
  94 | Entire Page | 100ms - 1000ms |
  95
  96 These ranges are rough, but should usually be what you expect from a page
  97 summary. If any of these numbers are way off (for example, "Event" is taking
  98 50% of runtime), that points toward a possible problem in that section of the
  99 code, and can guide you to examining the related service calls more carefully.
 100
 101 **Duration**: In the Duration column, look for service calls that take a long
 102 time. Sometimes these calls are just what the page is doing, but sometimes they
 103 may indicate a problem.
 104
 105 Some questions that may help understanding this column are: are there a small
 106 number of calls which account for a majority of the total page generation time?
 107 Do these calls seem fundamental to the behavior of the page, or is it not clear
 108 why they need to be made? Do some of them seem like they could be cached?
 109
 110 If there are queries which look slow, using the "Analyze Query Plans" button
 111 may help reveal poor query plans.
 112
 113 Generally, this column can help pinpoint these kinds of problems:
 114
 115   - Queries or other service calls which are huge and inefficient.
 116   - Work the page is doing which it could cache instead.
 117   - Problems with network services.
 118   - Missing keys or poor query plans.
 119
 120 **Repeated Calls**: In the "Details" column, look for service calls that are
 121 being made over and over again. Sometimes this is normal, but usually it
 122 indicates a call that can be batched or cached.
 123
 124 Some things to look for are: are similar calls being made over and over again?
 125 Do calls mostly make sense given what the page is doing? Could any calls be
 126 cached? Could multiple small calls be collected into one larger call? Are any
 127 of the service calls clearly goofy nonsense that shouldn't be happening?
 128
 129 Generally, this column can help pinpoint these kinds of problems:
 130
 131   - Unbatched queries which should be batched (see
 132     @{article:Performance: N+1 Query Problem}).
 133   - Opportunities to improve performance with caching.
 134   - General goofiness in how service calls are working.
 135
 136 If the services tab looks fine, and particularly if a page is slow but the
 137 "All Services" cost is small, that may indicate a problem in PHP. The best
 138 tool to understand problems in PHP is XHProf.
 139
 140
 141 Plugin: Startup
 142 ===============
 143
 144 The "Startup" plugin shows information about startup phases. This information
 145 can provide insight about performance problems which occur before the profiler
 146 can start.
 147
 148 Normally, the profiler is the best tool for understanding runtime performance,
 149 but some work is performed before the profiler starts (for example, loading
 150 libraries and configuration). If there is a substantial difference between the
 151 wall time reported by the profiler and the "Entire Page" cost reported by the
 152 Services tab, the Startup tab can help account for that time.
 153
 154 It is normal for starting the profiler to increase the cost of the page
 155 somewhat: the profiler itself adds overhead while it is running, and the page
 156 must do some work after the profiler is stopped to save the profile and
 157 complete other shutdown operations.
 158
 159
 160 Plugin: XHProf
 161 ==============
 162
 163 The "XHProf" plugin gives you access to the XHProf profiler. To use it, you need
 164 to install the corresponding PHP plugin.
 165
 166 Once it is installed, you can use XHProf to profile the runtime performance of
 167 a page. This will show you a detailed breakdown of where PHP spent time. This
 168 can help find slow or inefficient application code, and is the most powerful
 169 general-purpose performance tool available.
 170
 171 For instructions on installing and using XHProf, see @{article:Using XHProf}.
 172
 173
 174 Next Steps
 175 ==========
 176
 177 Continue by:
 178
 179   - installing XHProf with @{article:Using XHProf}; or
 180   - understanding and reporting performance issues with
 181     @{article:Troubleshooting Performance Problems}.