Add pantsd client profiling (#5434)

### Problem

As discovered in #5433, our current profiling does not cover an important case: the client in a `pantsd` session.

### Solution

Add another profiling entrypoint to cover an entire client session with `pantsd` enabled, and document the options.

src/docs/invoking.md

@@ -142,3 +142,23 @@ To enable the daemon, see the example in `pants.daemon.ini` in the root of the p
 
 The daemon will be in beta until the caveat mentioned above is addressed, but we hope to
 enable the daemon by default for the [`1.5.0` release of pants](https://github.com/pantsbuild/pants/milestone/12).
+
+Profiling Pants
+---------------
+
+There are three environment variables that profile various parts of a pants run.
+
+* `PANTS_PROFILE` - Covers the entire run when pantsd is disabled, or the post-fork portion
+  of a pantsd run.
+* `PANTSC_PROFILE` - Covers the client in a pantsd run, which connects to pantsd and then
+  communicates on the socket until the run completes.
+* `PANTSD_PROFILE` - Covers the graph warming operations pre-fork in a pantsd run.
+
+To enable profiling, set the relevant environment variable to a path to write a profile to, and
+then run pants:
+
+    :::bash
+    PANTS_PROFILE=myprofile.prof ./pants ..
+
+Once you have a profile file, you can use any visualizer that supports python profiles, such as
+`snakeviz` or `gprof2dot`.

src/python/pants/bin/pants_exe.py

@@ -5,8 +5,11 @@
 from __future__ import (absolute_import, division, generators, nested_scopes, print_function,
                         unicode_literals, with_statement)
 
+import os
+
 from pants.base.exiter import Exiter
 from pants.bin.pants_runner import PantsRunner
+from pants.util.contextutil import maybe_profiled
 
 
 TEST_STR = 'T E S T'
@@ -28,7 +31,8 @@ def main():
   exiter = Exiter()
   exiter.set_except_hook()
 
-  try:
-    PantsRunner(exiter).run()
-  except KeyboardInterrupt:
-    exiter.exit_and_fail(b'Interrupted by user.')
+  with maybe_profiled(os.environ.get('PANTSC_PROFILE')):
+    try:
+      PantsRunner(exiter).run()
+    except KeyboardInterrupt:
+      exiter.exit_and_fail(b'Interrupted by user.')