Using the UAS
The Java UAS is accessed via the UAS Management Console web interface that is
provided by a Management Console process. Its primary uses are to define the cloud regions
that are to be able to request application runs on a UAS and to install users' Java applications
into a UAS.
It also allows users to monitor their loaded applications and carry out fault diagnosis.
Access to the Management Console can be restricted by setting account logon details.
The Management Console provides the control of cloud connections, applications, UAS settings and access
to some diagnostic features:
In addition, users may occasionally need to configure some aspects of these services:
Or control them from the command line:
Using the Management Console
The Management Console runs on the same platform as the UAS. It can be accessed
remotely if required (dependent on firewall settings) on the
browser
port
(default is 38000). Locally its address is by default http://localhost:38000.
Managing Cloud Connections
A UAS can respond to application requests from one or more specific cloud regions.
Each UAS must be told the details of the specific cloud region(s) on which to register. This registration
uses the details of an existing user account on that cloud.
Without this information an Aculab Cloud cannot direct calls to be handled by the UAS.
The Cloud Management page lists the currently configured cloud regions and the username of the account
it is registered with. It also shows a cloud status indicating whether the cloud region has any
existing connections.
To add a new cloud region
Press the
'Add a cloud' button and fill in the details.
Cloud region: see the
Cloud Regions description
on cloud.aculab.com for information on specifying Cloud regions. Username and Password should correspond to an existing user
account on that specified cloud region.
If the account details supplied match those on the chosen cloud region, the UAS attaches to it and
passes it a list of the applications available to run.
Managing UAS Applications
UAS Applications to be run on a UAS should be installed into the UAS via the Management Console.
The
Applications page of the Management Console lists the applications currently installed in the UAS
displaying the following information for each application:
- Application name - the name of the application.
- Version - the application’s .NET Assembly Version.
- Running - the number of application instances currently running.
- Completed - the number of application instances that have completed.
- Passed % - the percentage of application instances that have returned 0, or a positive value
(see UAS Application Rules).
- Failed - the number of application instances that have returned a negative value.
(see UAS Application Rules).
Note: The UAS implements an application monitor that will automatically abort an application instance
if it runs for more than a period of elapsed time specified in the UAS configuration. This
elapsed time can be modified per-application within the application.
Installing an Application
A new or updated application can be installed by clicking the
Install an Application button
on the
Applications page, specifying the UAS application file
(a Java class packaged in a jar file) to install. If the file adheres to the
UAS Application Rules
it will be copied into the UAS Applications directory and installed in the UAS ready for use.
Otherwise an error message will be displayed.
If a previous version of the application is already loaded, the new application file will
only be installed if the
Implementation-Versions differ.
See
UAS Application Rules to
explore the possible reasons why an application install may fail.
Removing an Application
An installed application can be removed by selecting the corresponding
remove
icon.
This will prompt for confirmation before uninstalling the application from the UAS. When uninstalled
the associated jar file is removed from the UAS Applications directory.
Changing UAS Settings
The UAS has a number of settings that can be changed at any time that control whether
requests to run applications are to be accepted or not.
The Settings page of the Management Console contains access to these settings as follows:
- Accept application requests - this UAS can/cannot receive new application requests
- Apply application limits - this UAS can receive new application requests depending on the number of concurrent applications currently running
So that:
Accept application requests = OFF: no new application invocations will be passed to this UAS.
Accept application requests = ON and
Apply application limits = OFF: new application invocations will always be passed
to this UAS.
Accept application requests = ON and
Apply application limits = ON: when the number of concurrent applications running
on this UAS reaches the
Upper Limit no further application invocations will be passed to this UAS, until this number reaches the
Lower Limit.
Obtaining Diagnostics
The Applications page displays current statistics for all applications. These indicate
how each application is performing. These values will be refreshed every few seconds.
The individual statistics for each application can be zeroed by clicking on the reset field.
To view more detailed information for a particular application, click on its name.
This displays additional information listing the various return codes encountered for that application with
their relative proportion of all runs expressed as a percentage.
Application Data Records (ADRs)
The ADRs page in the Management Console displays the twenty most recent ADRs
for failed application runs (i.e. those that have a negative return code).
Each ADR includes:
- Name - the name of the application.
- ID - the application’s unique ID.
- Start - the start time for the application instance.
- Duration - the duration of the application instance in seconds.
- Result - the return code from the application instance.
- CLI - the caller line identification for the inbound application instance.
- App args - the set of application parameters sent to the application instance.
- Out args - outbound arguments for the outbound application instance.
This list will be refreshed every few seconds.
Selecting the Hide args option will remove App args and Out args from the table.
This can be useful if the argument strings make the table too cluttered.
Logs
This displays the list of UAS log files.
- Filename - the log filename.
- Date - the log file’s last modification timestamp.
- Size - the size of the log file in kilobytes.
This list is not refreshed automatically.
Click on the log filename to download it. Click on delete to delete the log file.
To change the logging level, select the required level and click submit. Changing the log level will
have immediate effect.
Changing the Local Login Account
A local username and password (for Management Console access only) can be entered on the Account page.
If these are configured then they will be requested every time the Management Console is started.
The UAS server regularly measures the response time of each of its TCP connections to the cloud.
The measurement period is statically configurable
(see
RoundTripMeasurementPeriodSeconds).
These measurements are available in a statistical summary via a web service on the UAS.
The UAS service maintains a maximum and minimum response time and calculates a rolling average response time
over a configurable number of samples
(see
RoundTripMeanCount).
These stats can be obtained and reset via http Web Services implemented by the UAS on the
ConsolePort.
Posting
"cloudmetrics=get" will return the following statistics for each connection on each
active cloud:
- cloudid = the id of the cloud to which this data refers (in R-L-C form e.g. 0-2-0)
- minrespt = the minimum response time in seconds since the last reset
- maxrespt = the maximum response time in seconds since the last reset
- meanrespt = the mean response time in seconds over the last RoundTripMeanCount
samples taken by the UAS since the last reset
Posting
"cloudmetrics=R-L-C" (where R-L-C is the id of the cloud on which to reset the stats) will
reset these statistics.
Configuration
Configuring the UAS Service
The UAS service loads a configuration file when it starts up. This file is called
uasstartup.properties
and is located in the installation folder where the UAS jar file resides.
It can contain the following configuration parameters:
- ConsolePort
- the port number used to communicate with the Management Console
(default 38001, range 1024-65535)
- TraceLocation
- the trace file location
(default "Logs")
- TraceFileMaxKilobytes
- the maximum size of a single trace file in KB
(default 2000, range 100-20000)
- TraceFileCount
- the maximum number of trace files
(default 50, range 1-500)
- TraceMessages
- whether to log low level messages to and from the cloud
(default false, true/false)
- AdrLoggerFileMaxKilobytes
- the maximum size of a single Application Data Record file in KB
(default 2000, range 100-20000)
- AdrLoggerFileCount
- the maximum number of Application Data Record files
(default 50, range 1-500)
- ApplicationMonitorEnabled
- whether the application elapsed time monitor is enabled
(default true, true/false)
- MinutesMaxApplicationElapsedTime
- the maximum minutes an application can run
(default 240, range 5-1440)
- CmsSecureSocketsLayerEnabled
- whether the cloud media server connections use SSL
(default true, true/false)
- ConnectionRoundTripMonitorEnabled
- whether the cloud response time monitor is enabled
(default true, true/false)
- RoundTripMeanCount
- the number of measurements over which to calculate the rolling mean of cloud response time
(default 5, range 1-1000)
- RoundTripMeasurementPeriodSeconds
- the period in seconds between cloud response time measurements
(default 30, range 5-3600)
Changes to any of these values will not be applied until the UAS service is restarted
Configuring the UAS Management Console Service
The Management Console loads a configuration file when it starts up. This file is called
config.cfg
and is located in
ManagementConsole\config
within the installation folder.
It contains the following user-configurable options:
- username - the login credentials
- password - the login credentials
- browser - the port number for attaching to the Console
(default 38000, range 1024-65535)
- monitor - the port number used to communicate with the UAS service
(default 38001, range 1024-65535)
- cmthresh - cloud response time thresholds (amberMax, redMax, amberMin, redMax, amberMean, redMean)
(default 5,10,1,2,2,4)
Changes to any of these values will not be applied until the Management Console service is restarted
Command Line Interfaces
Using the UAS Command Line Interface
On Windows the UAS is installed as a Windows Service and started by the installation package.
The UAS can also be installed manually as a Linux daemon. On both Windows and Linux it has a
command line interface available.
The
UAS
executable jar that is located in the installation folder can be
installed/uninstalled as a Windows service or Linux Daemon that can be started/restarted/stopped
using the following command line parameters:
- -h, -help
- -i, -install
- -u, -uninstall
- -s, -start
- -r, -restart
- -x, -stop
- -d, -debug
The -debug command runs the UAS from the console. This mode is typically used only when debugging
applications.
Using the Management Console Command Line Interface
On Windows the UAS Management Console service is installed as a Windows Service and started by the
installation package.
The
UAS_Management_Console
executable that is located in the ManagementConsole folder
within the installation folder can be installed/updated/removed and started/stopped/restarted
using the following command line parameters:
- install
- update
- remove
- start
- stop
- restart
For the
install and
update commands a service startup option can be specified:
- --startup [manual/auto/disabled]
On Linux the UAS Management Console is started as a Python application.
Currently only Python 2.7 is supported.
The Management Console is started from a command line and the distribution can be found in the
ManagementConsole
directory under the UAS root directory.
From the command line:
- python launch_mc.pyc --daemon
- will start the Managment Console as a daemon.
- python launch_mc.pyc --dstop
- will stop the daemon
- python launch_mc.pyc --drestart
- will restart it.
Starting the Management Console without any options will run it in the command window. When running in this way, type 'quit'
on the command line to terminate it.
Further command line configuration options are available to override those in the configuration file.
- -h --help
- to print help.
- -p --password
- Default '', UAS Management Console login password.
- -u --username
- Default '', UAS Management Console login username.
- -b --browser
- Default 38000, UAS management console port number for browser connection.
- -m --monitor
- Default 38001, UAS port number for UAS management console connection.
- -d --metadata
- Default cloud.aculab.com:80, Connection for UAS metadata.
- -c --cmsthresh
- Default 5,10,1,2,2,4 the threshold values for the icons on the cloud connections page.
If the configuration file is missing and no command line options are given, the command line defaults are used and the default configuration file is written.