Performance Commands#

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.

  • 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 inteface, 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

  • 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.

  • 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.

    For details, see: Configurable Number of Queue Processes

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.

  • 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.