[X2Go-Commits] [x2gobroker] 04/07: x2gobroker/loadchecker.py: Provide/improve API documentation for the load checker.

git-admin at x2go.org git-admin at x2go.org
Thu Sep 13 15:26:36 CEST 2018


This is an automated email from the git hooks/post-receive script.

x2go pushed a commit to branch master
in repository x2gobroker.

commit 623cf13fb17dc077a5dd6a9ebe39f6a824720b11
Author: Mike Gabriel <mike.gabriel at das-netzwerkteam.de>
Date:   Thu Sep 13 09:08:36 2018 +0200

    x2gobroker/loadchecker.py: Provide/improve API documentation for the load checker.
---
 x2gobroker/loadchecker.py | 115 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 104 insertions(+), 11 deletions(-)

diff --git a/x2gobroker/loadchecker.py b/x2gobroker/loadchecker.py
index ed1e686..5683555 100644
--- a/x2gobroker/loadchecker.py
+++ b/x2gobroker/loadchecker.py
@@ -18,6 +18,42 @@
 # Free Software Foundation, Inc.,
 # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
 
+"""\
+The X2Go Broker Load Checker is an auxiliary X2Go Session Broker service
+that checks the load on associated X2Go Servers in regular intervals.
+
+The load of an X2Go Server gets checked by the Load Checker, if
+
+  * an X2Go Server is part of a multi-server session profile
+  * the remote X2Go Server can be queried via X2Go Broker Agent
+  * the session profile (or the broker globally) is configured for
+    background load checking (see global config parameter: ``load-checker``
+    in ``/etc/x2go/x2gobroker.conf``
+
+In non-load-checker setups, multi-server session profiles perform a check
+on all configured servers during the login phase of a user. On big server
+farms, this check-them-all call to all members of the X2Go Server farm
+can be really time consuming.
+
+The solution is to run the X2Go Broker Load Checker service on the broker
+host and let it query server availability and load in regular intervals.
+It collects the server metrics and stores them in memory. If the broker
+receives a :func:`select_session()
+<x2gobroker.brokers.base.X2GoBroker.select_session()>` request from an
+X2Go client application, it will then negotiate with the load checker to
+work out, what X2Go Server is best for this incoming request.
+
+On the X2Go Servers, the X2Go Broker Agent calculates a ``load_factor`` that
+gets passed back to the X2Go Broker Load Checker when queried::
+
+
+                   ( memAvail/1000 ) * numCPUs * typeCPUs
+     load-factor = --------------------------------------   + 1
+                         loadavg*100 * numSessions
+
+
+"""
+
 import threading
 import time
 import copy
@@ -30,6 +66,39 @@ from x2gobroker.loggers import logger_broker
 
 
 def check_load(backend, profile_id, hostname=None):
+    """\
+    This function gets called from the broker daemon's side whenever the
+    broker needs information about associated X2Go Servers. It represents
+    the client-side of the load checking process in X2Go Session Broker.
+
+    It either sends a one liner 3-tuple::
+
+      <backend>\\r<profile_id>\\r<hostname>\\n
+
+    or a one liner 2-tuple::
+
+      <backend>\\r<profile_id>\\n
+
+    to the ``X2GOBROKER_LOADCHECKER_SOCKET`` (see
+    :mod:`x2gobroker.defaults`) and expects a number (if the hostname was
+    included in the query) or a Python dictionary (if only ``backend``
+    and ``profile_id`` had been given) as return value: the load
+    factor(s)
+
+    :param backend: the broker backend in use
+    :type backend: ``str``
+    :param profile_id: the session profile's ID
+    :type profile_id: ``str``
+    :param hostname: the X2Go Server's hostname as shown in
+        ``x2golistsessions``'s output
+    :type hostname: ``str``
+
+    :returns: either the load factor of the asked for server (as ``int``) or
+        the load factors (as ``dict``) of all server members of the given session profile
+        server
+    :rtype: ``int`` or ``dict``
+
+    """
     s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
     logger_broker.debug('loadchecker.check_load(): connecting to load checker service socket {socket}'.format(socket=x2gobroker.defaults.X2GOBROKER_LOADCHECKER_SOCKET))
     try:
@@ -89,13 +158,27 @@ def check_load(backend, profile_id, hostname=None):
 
 
 class LoadChecker(threading.Thread):
-
+    """\
+    The :class:`LoadChecker` class provides the functionality of setting up
+    a load checker service. It is the brain of the ``x2gobroker-loadchecker``
+    executable.
+
+    With it you can instantiate a new LoadChecker object for querying
+    remote X2Go Broker Agent instances about server/system load, CPU
+    usage, etc. in regular intervals.
+
+    :param config_file: global ``x2gobroker`` config file
+    :type config_file: a :mod:`configparser` compliant ``<obj>``
+    :param config_defaults: default (hard-coded) configuration parameters
+        for all parameters missing in the ``config_file``
+    :type config_defaults: ``dict``
+    :param logger: a :mod:`logging` instance
+    :type logger: ``<obj>``
+    :param kwargs: Any other parameter (for future features' compatibility, all ignored for now)
+    :type kwargs: ``dict``
+
+    """
     def __init__(self, config_file=None, config_defaults=None, logger=None, **kwargs):
-        """\
-        Initialize a new LoadChecker instance for querying remote X2Go Broker Agent instances
-        about server/system load, CPU usage, etc.
-
-        """
         self.logger = logger
 
         self.config_file = config_file
@@ -111,7 +194,7 @@ class LoadChecker(threading.Thread):
 
     def get_server_load(self, backend, profile_id, hostname):
         """\
-        Retrieve system load for a given server (via broker backend,
+        Retrieve system load factor for a given server (via broker backend,
         profile ID and hostname).
 
         :param backend: broker backend to query.
@@ -132,15 +215,15 @@ class LoadChecker(threading.Thread):
 
     def get_profile_load(self, backend, profile_id):
         """\
-        Retrieve system load for all servers for a given profile ID (and a given
-        broker backend).
+        Retrieve system load factors for all member servers of the given
+        profile ID (and the given broker backend).
 
         :param backend: broker backend to query.
         :type backend: ``str``
         :param profile_id: profile ID of the session profile to query
         :type profile_id: ``str``
 
-        :returns: load factor of the given server (or None if an error occurs)
+        :returns: load factors of the given profile ID (or None if an error occurs)
         :rtype: ``dict``
 
         """
@@ -151,7 +234,10 @@ class LoadChecker(threading.Thread):
 
     def loadchecker(self):
         """\
-        This is the actual thread runner that queries configured / available X2Go Broker Agents in regular
+        This is the actual thread runner of the :class:`LoadChecker``
+        class.
+
+        It queries configured / available X2Go Broker Agents in regular
         intervals about system load, CPU types and usage.
 
         """
@@ -241,4 +327,11 @@ class LoadChecker(threading.Thread):
                 time_to_sleep = 0
 
     def stop_thread(self):
+        """\
+        Induce a stop of the running :class:`LoadChecker`' thread.
+
+        When stopped, no more queries to remote X2Go Servers will be
+        made.
+
+        """
         self.keep_alive = False

--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git


More information about the x2go-commits mailing list