Add document about monitoring/debugging. [skip ci]

doc/_about.rst

+gevent is a coroutine_ -based Python_ networking library that uses
+greenlet_ to provide a high-level synchronous API on top of the `libev`_
+or `libuv`_ event loop.
+
+Features include:
+
+
+* Fast event loop based on `libev`_ or `libuv`_
+* Lightweight execution units based on greenlet_.
+* API that re-uses concepts from the Python standard library (for
+  examples there are :class:`events <gevent.event.Event>` and
+  :class:`queues <gevent.queue.Queue>`).
+* :ref:`Cooperative sockets with SSL support <networking>`
+* :doc:`Cooperative DNS queries <dns>` performed through a threadpool,
+  dnspython, or c-ares.
+* :ref:`Monkey patching utility <monkey-patching>` to get 3rd party modules to become cooperative
+* TCP/UDP/HTTP servers
+* Subprocess support (through :mod:`gevent.subprocess`)
+* Thread pools
+
+.. _coroutine: https://en.wikipedia.org/wiki/Coroutine
+.. _Python: http://python.org
+.. _greenlet: https://greenlet.readthedocs.io
+.. _libev: http://software.schmorp.de/pkg/libev.html
+.. _libuv: http://libuv.org

doc/api/gevent.greenlet.rst

@@ -103,11 +103,63 @@ yet and thus would evaluate to False.
 
 .. automethod:: Greenlet.__init__
 
+.. rubric:: Attributes
+
 .. autoattribute:: Greenlet.exception
 .. autoattribute:: Greenlet.minimal_ident
 .. autoattribute:: Greenlet.name
 .. autoattribute:: Greenlet.dead
 
+.. attribute:: Greenlet.value
+
+   Holds the value returned by the function if the greenlet has
+   finished successfully. Until then, or if it finished in error, `None`.
+
+   .. tip::
+
+      Recall that a greenlet killed with the default
+      :class:`GreenletExit` is considered to have finished
+      successfully, and the `GreenletExit` exception will be its
+      value.
+
+
+.. attribute:: Greenlet.spawn_tree_locals
+
+   A dictionary that is shared between all the greenlets in a "spawn
+   tree", that is, a spawning greenlet and all its descendent
+   greenlets. All children of the main (root) greenlet start their own
+   spawn trees. Assign a new dictionary to this attribute on an
+   instance of this class to create a new spawn tree (as far as locals
+   are concerned).
+
+   .. versionadded:: 1.3a2
+
+.. attribute:: Greenlet.spawning_greenlet
+
+   A weak-reference to the greenlet that was current when this object
+   was created. Note that the :attr:`parent` attribute is always the
+   hub.
+
+   .. versionadded:: 1.3a2
+
+.. attribute:: Greenlet.spawning_stack
+
+   A lightweight frame-like object capturing the stack when
+   this greenlet was created as well as the stack when the spawning
+   greenlet was created (if applicable). This can be passed to
+   :func:`traceback.print_stack`.
+
+   .. versionadded:: 1.3a2
+
+.. attribute:: Greenlet.spawning_stack_limit
+
+   A class attribute specifying how many levels of the spawning stack
+   will be kept. Specify a smaller number for higher performance,
+   spawning greenlets, specify a larger value for improved debugging.
+
+   .. versionadded:: 1.3a2
+
+
 .. rubric:: Methods
 
 .. automethod:: Greenlet.spawn

doc/contents.rst

@@ -10,10 +10,11 @@ Introduction and Basics
 
    intro
    whatsnew_1_3
-   configuration
    api/gevent
    servers
    dns
+   monitoring
+   configuration
    changelog
 
 API Details

doc/index.rst

@@ -2,23 +2,7 @@
  What is gevent?
 =================
 
-gevent is a coroutine_ -based Python_ networking library that uses
-greenlet_ to provide a high-level synchronous API on top of the `libev`_
-or `libuv`_ event loop.
-
-Features include:
-
-* Fast event loop based on `libev`_ or `libuv`_
-* Lightweight execution units based on greenlet_.
-* API that re-uses concepts from the Python standard library (for
-  examples there are :class:`events <gevent.event.Event>` and
-  :class:`queues <gevent.queue.Queue>`).
-* :ref:`Cooperative sockets with SSL support <networking>`
-* :doc:`Cooperative DNS queries <dns>` performed through a threadpool, dnspython, or c-ares.
-* :ref:`Monkey patching utility <monkey-patching>` to get 3rd party modules to become cooperative
-* TCP/UDP/HTTP servers
-* Subprocess support (through :mod:`gevent.subprocess`)
-* Thread pools
+.. include:: _about.rst
 
 
 gevent is `inspired by eventlet

doc/intro.rst

@@ -2,32 +2,7 @@
  Introduction
 ==============
 
-gevent is a coroutine_ -based Python_ networking library that uses
-greenlet_ to provide a high-level synchronous API on top of the `libev`_
-or `libuv`_ event loop.
-
-Features include:
-
-
-* Fast event loop based on `libev`_ or `libuv`_
-* Lightweight execution units based on greenlet_.
-* API that re-uses concepts from the Python standard library (for
-  examples there are :class:`events <gevent.event.Event>` and
-  :class:`queues <gevent.queue.Queue>`).
-* :ref:`Cooperative sockets with SSL support <networking>`
-* :doc:`Cooperative DNS queries <dns>` performed through a threadpool,
-  dnspython, or c-ares.
-* :ref:`Monkey patching utility <monkey-patching>` to get 3rd party modules to become cooperative
-* TCP/UDP/HTTP servers
-* Subprocess support (through :mod:`gevent.subprocess`)
-* Thread pools
-
-.. _coroutine: https://en.wikipedia.org/wiki/Coroutine
-.. _Python: http://python.org
-.. _greenlet: https://greenlet.readthedocs.io
-.. _libev: http://software.schmorp.de/pkg/libev.html
-.. _libuv: http://libuv.org
-
+.. include:: _about.rst
 
 .. _installation:
 

doc/monitoring.rst

+==============================================
+ Monitoring and Debugging gevent Applications
+==============================================
+
+gevent applications are often long-running server processes. Beginning
+with version 1.3, gevent has special support for monitoring such
+applications and getting visibility into them.
+
+The Monitor Thread
+==================
+
+gevent can be :attr:`configured
+<gevent._config.Config.monitor_thread>` to start a native thread to
+watch over each hub it creates. Out of the box, that thread has
+support to watch two things, but you can :func:`add your own functions
+<gevent.events.IPeriodicMonitorThread.add_monitoring_function>` to be
+called periodically in this thread.
+
+Blocking
+--------
+
+When the monitor thread is enabled, by default it will watch for
+greenlets that block the event loop for longer than a
+:attr:`configurable <gevent._config.Config.max_blocking_time>` time
+interval. When such a blocking greenlet is detected, it will print
+:func:`a report <gevent.util.format_run_info>` to the hub's
+:attr:`~gevent.hub.Hub.exception_stream`. It will also emit the
+:class:`gevent.events.EventLoopBlocked` event.
+
+
+Memory Usage
+------------
+
+Optionally, you can set a :attr:`memory limit
+<gevent._config.Config.max_memory_usage>`. The monitor thread will
+check the process's memory usage every
+:attr:`~gevent._config.Config.memory_monitor_period` seconds, and if
+it is found to exceed this value, the
+:class:`gevent.events.MemoryUsageThresholdExceeded` event will be
+emitted. If in the future memory usage declines below the configured
+value, the :class:`gevent.events.MemoryUsageUnderThreshold` event will
+be emitted.
+
+.. important::
+
+   `psutil <https://pypi.org/project/psutil>`_ must be
+   installed to monitor memory usage.
+
+Visibility
+==========
+
+It is sometimes useful to get an overview of all existing greenlets
+and their stack traces. The function
+:func:`gevent.util.print_run_info` will collect this info and print it
+(:func:`gevent.util.format_run_info` only collects and returns this
+information). The greenlets are organized into a tree based on the
+greenlet that spawned them.
+
+For each greenlet the following information is printed:
+
+- Its current execution stack
+- If it is not running, its termination status and
+  :attr:`gevent.Greenlet.value` or
+  :attr:`gevent.Greenlet.exception`
+- The :attr:`stack at which it was spawned
+  <gevent.Greenlet.spawning_stack>`
+- Its parent (usually the hub)
+- Its :attr:`~gevent.Greenlet.minimal_ident`
+- Its :attr:`~gevent.Greenlet.name`
+- The :attr:`spawn tree locals <gevent.Greenlet.spawn_tree_locals>`
+  (only for the root of the spawn tree).
+- The dicts of all :class:`gevent.local.local` objects that are used
+  in the greenlet.
+
+The greenlet tree itself is represented as an object that you can also
+use for your own purposes: :class:`gevent.util.GreenletTree`.
+
+
+Profiling
+=========
+
+The github repository `nylas/nylas-perftools <https://github.com/nylas/nylas-perftools>`_ has some
+gevent-compatible profilers. ``stacksampler`` is meant to be run in a
+greenlet in your server process and exposes data through an HTTP
+server. ``py2devtools`` is a greenlet-aware profiler that outputs data
+that can be used by the Chrome dev tools.
+
+..  LocalWords:  greenlets gevent greenlet

src/gevent/_config.py

@@ -547,7 +547,9 @@ class MonitorMemoryMaxUsage(ByteCountSettingMixin, Setting):
     desc = """\
     If `monitor_thread` is enabled,
     then if memory usage exceeds this amount (in bytes), events will
-    be emitted. See `gevent.events`.
+    be emitted. See `gevent.events`. In the environment variable, you can use
+    a suffix of 'kb', 'mb' or 'gb' to specify the value in kilobytes, megabytes
+    or gigibytes.
 
     There is no default value for this setting. If you wish to
     cap memory usage, you must choose a value.

src/gevent/greenlet.py

@@ -164,61 +164,14 @@ class Greenlet(greenlet):
             object. Previously, passing a non-callable object would fail after the greenlet
             was spawned.
 
-        .. rubric:: Attributes
-
-        .. attribute:: value
-
-            Holds the value returned by the function if the greenlet has
-            finished successfully. Until then, or if it finished in error, `None`.
-
-            .. tip:: Recall that a greenlet killed with the default
-                     :class:`GreenletExit` is considered to have finished
-                     successfully, and the `GreenletExit` exception will be
-                     its value.
-
-
-        .. attribute:: spawn_tree_locals
-
-            A dictionary that is shared between all the greenlets
-            in a "spawn tree", that is, a spawning greenlet and all
-            its descendent greenlets. All children of the main (root)
-            greenlet start their own spawn trees. Assign a new dictionary
-            to this attribute on an instance of this class to create a new
-            spawn tree (as far as locals are concerned).
-
-            .. versionadded:: 1.3a2
-
-        .. attribute:: spawning_greenlet
-
-            A weak-reference to the greenlet that was current when this object
-            was created. Note that the :attr:`parent` attribute is always the
-            hub.
-
-            .. versionadded:: 1.3a2
-
-        .. attribute:: spawning_stack
-
-           A lightweight frame-like object capturing the stack when
-           this greenlet was created as well as the stack when the spawning
-           greenlet was created (if applicable). This can be passed to
-           :func:`traceback.print_stack`.
-
-            .. versionadded:: 1.3a2
-
-        .. attribute:: spawning_stack_limit
-
-            A class attribute specifying how many levels of the spawning
-            stack will be kept. Specify a smaller number for higher performance,
-            spawning greenlets, specify a larger value for improved debugging.
-
-            .. versionadded:: 1.3a2
-
         .. versionchanged:: 1.3b1
            The ``GEVENT_TRACK_GREENLET_TREE`` configuration value may be set to
            a false value to disable ``spawn_tree_locals``, ``spawning_greenlet``,
            and ``spawning_stack``. The first two will be None in that case, and the
            latter will be empty.
         """
+        # The attributes are documented in the .rst file
+
         # greenlet.greenlet(run=None, parent=None)
         # Calling it with both positional arguments instead of a keyword
         # argument (parent=get_hub()) speeds up creation of this object ~30%: