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@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