.. _voss-performance-commands:

Performance Commands
--------------------

.. _19.3.4-PB1|EKB-7871:
.. _21.3|VOSS-911:

.. index:: voss;voss throttle-rates


.. important::

   On a Modular Architecture deployment, ``voss`` system specific commands
   can only be run on application nodes and for Unified and Single Node architectures, *not* on database or web proxy type nodes.
  


* **voss throttle-rates** - A command with parameters to set, show and disable
  the API request rate for an interface or for any user. The command may be used to manage API
  request overload.

  * Throttle rates apply to each unified node in a cluster.
  * Use **voss throttle-rates help** to see command parameters and options.
  * Please contact support before changing any settings for throttle rates. 
    Great care should be taken when adjusting throttle rates, as a change
    can have a significant impact on system performance and behavior

  By default, the following interface throttle rates apply:
  
  * administration: disabled 
  * selfservice: 300 req/min
  * per user: 20 req/sec

  If the throttle rates are exceeded, the API returns the HTTP status code and message:

  ``Error 429: Too Many Requests``

  * To set throttling:

    **voss throttle-rates type <administration|selfservice|user> requests <number of requests> unit <time unit>**
  
    * The requests parameter is defined as an integer which is the number of requests per unit.
    * The time unit can be second (``sec``, ``s``) or minute (``min``, ``m``).
    * Command output will show the interface and configuration change and prompt for a service
      restart.

    Examples:

    ::

       $ voss throttle-rates type administration requests 10 unit min
           Administration: 
               Current Configuration: Disabled 
               New Configuration: 10/min
           Self Service: 
               Current Configuration: Disabled
           User: 
               Current Configuration: Disabled

         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi           
       
       
       $ voss throttle-rates type selfservice requests 20 unit sec
           Administration: 
               Current Configuration: 10/min
               Current Rates: 0/min 
           Self Service: 
               Current Configuration: Disabled 
               New Configuration: 20/sec
           User: 
               Current Configuration: Disabled
           
         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi           


       $ voss throttle-rates type user requests 30 unit min
           Administration: 
               Current Configuration: 10/min
               Current Rates: 0/min 
           Self Service: 
               Current Configuration: 20/sec
               Current Rates: 0/sec 
           User: 
               Current Configuration: Disabled 
               New Configuration: 30/min
           
         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi           

           
       


    Note:
   
    * If the command is used *without* parameters, the user will be prompted to enter
      them. Press **Ctrl-C** to exit this interactive mode.
    * The user throttle rate can be limited by an interface throttle rate.
    

  * To show current throttling continuously:
  
    **voss throttle-rates list-refresh**
  
    The current request values are updated until the command is 
    canceled with **Ctrl-C**.
  
    For example:
    
    ::
    
       $ voss throttle-rates list-refresh
           Administration: 
               Current Configuration: 10/min
               Current Rates: 0/min 
           Self Service: 
               Current Configuration: 20/sec
               Current Rates: 0/sec 
           User: 
               Current Configuration: 30/min
       Refreshing Ctrl-C to exit.. 
    
  
  * To show current throttling and exit:
  
    **voss throttle-rates list**
  
    The current request values are updated and shown. The
    command then exits.
  
    For example, to list when enabled:
    
    ::
  
       $ voss throttle-rates list
           Administration: 
               Current Configuration: 10/min
               Current Rates: 0/min 
           Self Service: 
               Current Configuration: 20/sec
               Current Rates: 0/sec 
           User: 
               Current Configuration: 30/min
           
       
    
    For example, to list when throttling is disabled:
    
    ::
  
       $ voss throttle-rates list
           Administration: 
               Current Configuration: Disabled
           Self Service: 
               Current Configuration: Disabled
           User: 
               Current Configuration: Disabled
           
       
  
  
  * To disable throttling:
  
    **voss throttle-rates disable**
  
    For example:
    
    ::
    
       $ voss throttle-rates disable
           Administration: 
               Current Configuration: 10/min 
               Current Rates: 0/min 
               New Configuration: Disabled
           Self Service: 
               Current Configuration: 20/sec 
               Current Rates: 0/sec 
               New Configuration: Disabled
           User: 
               Current Configuration: 30/min 
               New Configuration: Disabled
           
         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi           

           
       
  
    Throttle rates are disabled by default. To restore any rates that were disabled,
    the throttle rates need to be set again.



.. index:: voss;voss session-limits

* **voss session-limits** - A command with parameters to set, show and disable
  the number of sessions - based on interface and customer. In other words,
  for each interface: Administration or Self-service, a Global and a Per Customer
  Hierarchy session limit can be set. The number of concurrent login sessions per user
  is determined by the user's Credential Policy. Highest level (above provider administrators)
  administrator logins do not affect and are not affected by session limits.

  .. note::

     For administrators configured with multiple user roles, i.e. users that have a user type
     "Admin + End User":
     
     * Each SSO login will consume a session counter from the global/customer
       administration session limits.
     * Each non-SSO admin login will consume a session counter from the global/customer
       administration session limits.
     * Even if a SSO/non-SSO login admin switches to the Self-service interface, the session counter
       will remain consumed on the global/customer administration session limits.  

  Use **voss session-limits help** to see command parameters and options.
  Please contact support before changing any settings for session limits. 
  
  The command line output of the command to adjust the limits show the current and new
  values and prompt to restart the ``voss-deviceapi:voss-wsgi`` service before 
  the limit is changed. For clusters, the session limit is set per cluster,
  requiring a cluster wide service restart.

  By default, the following limits apply:
  
  * global administration: 200 
  * global selfservice: 20000 
  * per customer administration : 10
  * per customer selfservice : 1000

  The global session limit would always be set to a larger value than a customer
  hierarchy limit.

  A session is active until it expires or the user logs out. If the session limits are
  exceeded, the API returns the HTTP status code and message:

  ``Error 503: "Login is currently disabled due to a temporary overload. Please try again later.``


  * To set session limits:

    **voss session-limits type <customer|global> interface <administration|selfservice> limit <number>**
  
    * If the command is used *without* parameters, the user will be prompted to enter
      them. Press **Ctrl-C** to exit this interactive mode.
    * The type is the hierarchy to which the limit applies: ``global`` or ``customer``
    * The interface is the user interface to which the limit applies: ``Administration`` or ``Self-service``.
    * The limit number is an integer value for the number of sessions.

    Examples:

    ::

       $ voss session-limits type customer interface administration limit 100
         Administration: 
               Global: 
                   Current Limit: 200
                   Current Sessions: 1
               Per Customer Hierarchy: 
                   Current Limit: 10
                   New Limit: 100
           Self Service: 
               Global: 
                   Current Limit: 20000
                   Current Sessions: 0
               Per Customer Hierarchy: 
                   Current Limit: 1000
           
         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi           


  * To list session limits:

    **voss session-limits <list|list-refresh>**
  
    The current session values are shown. if the ``list-refresh`` option is
    used, the values are updated every second until the command
    is canceled with **Ctrl-C**.
  

    Examples for two customers "GenCorp" and "VS-Corp":

    ::

        $ voss session-limits list-refresh
            Administration: 
                Global: 
                    Current Limit: 200
                    Current Sessions: 2
                Per Customer Hierarchy: 
                    Current Limit: 10
                    GenCorp Current Sessions: 0
                    VS-Corp Current Sessions: 1
            Self Service: 
                Global: 
                    Current Limit: 20000
                    Current Sessions: 0
                Per Customer Hierarchy: 
                    Current Limit: 1000
                    GenCorp Current Sessions: 0
                    VS-Corp Current Sessions: 0

            Refreshing, Ctrl-C to exit...


  * To disable session limits:

    **voss session-limits disable**
  
    * This setting *removes all* session limit settings.
    * Recall that for the command to take effect, *all* nodes in the cluster need the service 
      to be restarted.
    * To restore any settings that were disabled, they need to be set again.

    Example:

    ::

       $ voss session-limits disable
         Administration: 
             Global: 
                 Current Limit: 200
                 Current Sessions: 1
                 New Limit: Disabled
             Per Customer Hierarchy: 
                 Current Limit: 10
                 New Limit: Disabled
         Self Service: 
             Global: 
                 Current Limit: 20000
                 Current Sessions: 0
                 New Limit: Disabled
             Per Customer Hierarchy: 
                 Current Limit: 1000
                 New Limit: Disabled

         An application restart is required for this change to take effect, e.g.:
         $ cluster run application app start voss-deviceapi:voss-wsgi



.. index:: voss;voss workers

* **voss workers** - By default, 30 is the maximum number of parent transactions
  per unified node from the queue that will be processed at once. Use the
  command **voss workers <number>** to modify this value.

  This command restarts the ``voss-queue`` services.


.. index:: voss;voss queues


* **voss queues <number>** - Set the number of queue processes

  Increasing the number of queues that can run in parallel. 
  This command restarts the ``voss-queue`` services.

  **voss queues** - Get the number of queue processes 

  .. important::

     It is strongly advised that VOSS Support is consulted before making changes to the number of queue processes.  


  .. raw:: html
    
     <p>For details, see: <a href="../best-practices/best-prac-overload-cntrl-number-of-queues.html">Configurable Number of Queue Processes</a></p>
  
  .. raw:: latex
  
     For details, see the Configurable Number of Queue Processes topic in the Best Practices Guide.






Transactions resulting from a number of system components are by default carried out with a 
low priority that is currently limited to 50% of the maximum allowed parent transactions 
to be processed at once (the default is 30 per unified node). The system components are:

* Bulk loaders
* Data Sync (CUCM, Unity, LDAP)

Since these transactions may place too much load on the system during business hours when users are using
the system for other activities, commands are available to change the percentage of the maximum allowed 
number of transactions these low priority tasks can use at peak and off-peak times.

* Percentage options are: 20%, 50% and 80%
* Defaults are as follows:

  * Off-peak percentage is 50% of the maximum number of parent transactions
    per unified node from the queue that will be processed at once. This means if no
    off-peak percentage is set manually, this value will be the default. 
  * Off-peak start and end times on weekdays (Mon - Fri) are 00:00 - 23:59
  * Off-peak start and end times on weekends (Sat - Sun) are 00:00 - 23:59

  In other words, the default is 50% for all hours of the week.

The command that is available to change peak and off-peak times and 
percentages, is **voss worker low_priority_schedule** and takes
a number of parameters.

Without parameters, the command shows the current times and percentages,
for example:

::
  
    $ voss worker low_priority_schedule
    
           Off-peak Time:
               Weekday:
                   Start Time: 00:00
                   End Time: 23:59
               Weekend:
                   Start Time: 00:00
                   End Time: 23:59
           Off-peak Percentage: 50
           Peak Percentage: 50    

The following list shows command parameters
to set times and percentages for the
low priority schedule. Note that if an end time is set
to a value that falls into another schedule, the start time 
of the other schedule will apply.


.. index:: voss;voss worker


* **voss worker low_priority_schedule off_peak_time weekday HH:MM HH:MM**

  * Set the weekday schedule off-peak start and end time.
    The command prompts for a queue service restart.

    The command supports nodes in different time zones. When times are set on
    a node in a cluster, the equivalent schedule times are set on nodes in
    other time zones.

* **voss worker low_priority_schedule off_peak_time weekend  HH:MM HH:MM**

  * Set the weekend schedule off-peak start and end time.
    The command prompts for a queue service restart.

    The command supports nodes in different time zones: when times are set on
    a node in a cluster, the equivalent schedule times are set on nodes in
    other time zones.

* **voss worker low_priority_schedule peak_percentage [20|50|80]**

  * Set the percentage of maximum allowed workers for low priority tasks
    to either 20%, 50%, or 80% during the  peak period - the period outside any defined off-peak
    period. The command prompts for a queue service restart.

* **voss worker low_priority_schedule off_peak_percentage [20|50|80]**

  * Set the percentage of maximum allowed workers for low priority tasks
    to either 20%, 50%, or 80% at the defined off-peak period.
    The command prompts for a queue service restart.

For example, the sequence of commands:

::

   voss worker low_priority_schedule off_peak_time weekday 23:00 04:00
   voss worker low_priority_schedule off_peak_time weekend 13:00 10:00
   voss worker low_priority_schedule off_peak_percentage 80
   voss worker low_priority_schedule peak_percentage 20
  
will result in a low priority schedules that uses a higher percentage (80%) of
the maximum workers on weekdays between 23:00 and 04:00 and on weekends between
13:00 and 10:00, and only 20% during the rest of the time - the peak time.








.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM