@@ -765,13 +765,71 @@ serialization.
765765Running a logging socket listener in production
766766^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
767767
768- To run a logging listener in production, you may need to use a process-management tool
769- such as `Supervisor <http://supervisord.org/ >`_. `Here
770- <https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b> `_ is a Gist which
771- provides the bare-bones files to run the above functionality using Supervisor: you
772- will need to change the ``/path/to/ `` parts in the Gist to reflect the actual paths you
773- want to use.
774-
768+ .. _socket-listener-gist : https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b
769+
770+ To run a logging listener in production, you may need to use a
771+ process-management tool such as `Supervisor <http://supervisord.org/ >`_.
772+ `Here is a Gist <socket-listener-gist _>`__
773+ which provides the bare-bones files to run the above functionality using
774+ Supervisor. It consists of the following files:
775+
776+ +-------------------------+----------------------------------------------------+
777+ | File | Purpose |
778+ +=========================+====================================================+
779+ | :file: `prepare.sh ` | A Bash script to prepare the environment for |
780+ | | testing |
781+ +-------------------------+----------------------------------------------------+
782+ | :file: `supervisor.conf ` | The Supervisor configuration file, which has |
783+ | | entries for the listener and a multi-process web |
784+ | | application |
785+ +-------------------------+----------------------------------------------------+
786+ | :file: `ensure_app.sh ` | A Bash script to ensure that Supervisor is running |
787+ | | with the above configuration |
788+ +-------------------------+----------------------------------------------------+
789+ | :file: `log_listener.py ` | The socket listener program which receives log |
790+ | | events and records them to a file |
791+ +-------------------------+----------------------------------------------------+
792+ | :file: `main.py ` | A simple web application which performs logging |
793+ | | via a socket connected to the listener |
794+ +-------------------------+----------------------------------------------------+
795+ | :file: `webapp.json ` | A JSON configuration file for the web application |
796+ +-------------------------+----------------------------------------------------+
797+ | :file: `client.py ` | A Python script to exercise the web application |
798+ +-------------------------+----------------------------------------------------+
799+
800+ The web application uses `Gunicorn <https://gunicorn.org/ >`_, which is a
801+ popular web application server that starts multiple worker processes to handle
802+ requests. This example setup shows how the workers can write to the same log file
803+ without conflicting with one another --- they all go through the socket listener.
804+
805+ To test these files, do the following in a POSIX environment:
806+
807+ #. Download `the Gist <socket-listener-gist _>`__
808+ as a ZIP archive using the :guilabel: `Download ZIP ` button.
809+
810+ #. Unzip the above files from the archive into a scratch directory.
811+
812+ #. In the scratch directory, run ``bash prepare.sh `` to get things ready.
813+ This creates a :file: `run ` subdirectory to contain Supervisor-related and
814+ log files, and a :file: `venv ` subdirectory to contain a virtual environment
815+ into which ``bottle ``, ``gunicorn `` and ``supervisor `` are installed.
816+
817+ #. Run ``bash ensure_app.sh `` to ensure that Supervisor is running with
818+ the above configuration.
819+
820+ #. Run ``venv/bin/python client.py `` to exercise the web application,
821+ which will lead to records being written to the log.
822+
823+ #. Inspect the log files in the :file: `run ` subdirectory. You should see the
824+ most recent log lines in files matching the pattern :file: `app.log* `. They won't be in
825+ any particular order, since they have been handled concurrently by different
826+ worker processes in a non-deterministic way.
827+
828+ #. You can shut down the listener and the web application by running
829+ ``venv/bin/supervisorctl -c supervisor.conf shutdown ``.
830+
831+ You may need to tweak the configuration files in the unlikely event that the
832+ configured ports clash with something else in your test environment.
775833
776834.. _context-info :
777835
0 commit comments