Service Manager Console
Service Manager ConsoleThe Service Manager Console is invoked from a browser via the following URL:
http://<svcmgr_host>/xmarc/SvcMgr
where <svcmgr_host> is the machine on which the Service Manager has been installed.
This machine does not have to be the same machine which hosts the Service Brokers, Service Agents and Xmarc Services. However it is advisable that the same <svcmgr_host> is used for all sessions of the Service Manager because a running management configuration is maintained on that machine.
This of course will not work unless all the pieces have been correctly installed. Installation is discussed later.
The above URL will execute the SvcMgr servlet and produce the following web page:
Figure 1 Service Administration Login
As the screenshot illustrates, you are required to login to an administrative session. The default password is set to "X" (uppercase). Upon logging in, you are then presented with the screen shown below. It is recommended that you change the password from its default value. This can be done by clicking on the Change Password button near the foot of the left-hand frame (see Figure 2).
Figure 2 Initial Service Manager Screen
As you can see, the page is divided into 2 frames. The left frame contains a form for the input of Service Broker and Xmarc Service information. The right frame is used for the display of other information and any forms invoked by pressing buttons in the left frame. Initially the right frame has some general help information.
In this example <svcmgr_host> was specified as wrasse, actually one of the machines in Xmarc's internal network.
The Service Broker relays requests between a Client Application and an Xmarc Service.
In the upper part of the left-hand frame of the Services Manager page (Figure 2), there are 2 input fields which direct Service Manager operations to a particular Service Broker: Web Server and Servlet Path. Once set, these values define the "current" Service Broker we are going to administer.
Together, Web Server and Servlet Path tell the Service Manager where to find the Service Broker. Remember this is where the Service Broker is running, not necessarily where the Xmarc Services are running.
During a Service Manager session, it is usually the case that Web Server and Servlet Path are set at the beginning and then remain constant. It is rare for the Service Manager to be administering multiple sets of Service Brokers on different Web Servers.
In previous versions of the Service Manager (known then as WIISEAdmin) there were 3 different service brokers available: WIISE, FireStation and FireRender. These have since been merged into one, Broker. Any url references to the old servlet names are automatically redirected to Broker.
We must indicate where the Service Broker is running.
It runs on a Web Server which may or not be the same Web Server which hosts the Service Manager (in our case wrasse). Initially, the Service Manager assumes that the Web Server hosting the Service Broker and Service Manager is the same. That is why the Web Server text box shows the initial value wrasse.
If the Service Broker is running on a different Web Server, the value in the Web Server text box should be changed accordingly. In the subsequent examples we shall have a Service Broker running on a machine called anchovy.
The Servlet Path text box shows the path within the servlet container of Web Server where the Service Broker class file resides. This is typically a directory named xmarc. If it is not, this text box should be changed accordingly.
When this button is pressed, the Agent Administration Screen appears in the right-hand frame. In this screen, discussed in detail in a later section, remote Service Agents running under the current Service Broker can be administered.
When this button is pressed, the New Service Request Screen appears in the right-hand frame. In this screen, discussed in detail in a later section, new Xmarc Services may be created to run under the current Service Broker.
When this button is pressed, the Logging Administration Screen appears in the right-hand frame. In this screen, discussed in detail in a later section, the message logging level may be set for an Xmarc Service.
An Xmarc Service handles requests from a Client Application. It returns data to the Client Application via the Service Broker to which it is registered.
In the lower part of the left-hand frame of the Services Manager page (Figure 2), there are input fields which specify Xmarc Services. Below the input fields are buttons which, when pressed, direct the current Service Broker to perform some administrative operation on the specified service(s).
In order to service requests from multiple client applications rapidly, many instances of the same Xmarc Service can be running at the same time. When the Service Broker receives a request for such a service it directs the request to whichever one is free at the time, i.e. not currently servicing a request from another client.
Such a set of identical Xmarc Services is known as a "Logical Service", and all have the same Service Name. They may be running on different host machines, so each will have a unique host and port number (Host:Port) so that the Service Broker can communicate with them. In the case of C++ services, each instance of a service is a separate process. In the case of Java services, each is a separate thread running in a shared Java Virtual Machine.
Some Services can be given a Secret Key, to restrict administration access to authorized personnel only.
This text field indicates which service is of interest to the operator. The name is that given to the service when it was created, via the New Service Request Screen.
The name is that of a Logical Service, which may be shared by multiple instances of the service. By filling in the Host:Port field, sets of identical services running on the same host, or individual service instances may be selected.
Example:
Service Name = GEODB_SVC
Host:Port = <blank>
This will select all instances of the GEODB_SVC Xmarc Service running on all hosts registered with the current Service Broker.
This text field further qualifies which service instance (or instances) are of interest to the operator. The host for an Xmarc Service is the machine on which it is running, indicated when the service was kicked off via the New Service Request Screen. The port for an Xmarc Service is the port through which it communicates with its Service Broker, also indicated via the New Service Request Screen, or supplied automatically by the system. Instances are displayed in the Report tables. Omitting the :Port part implies all service instances on that host. This field is only used by the Report button.
Example:
Service Name = GEODB_SVC
Host:Port = shark
This will select all instances of the GEODB_SVC Xmarc Service running on machine shark registered with the current Service Broker.
Example
Service Name = GEODB_SVC
Host:Port = shark:1285
This will select a particular instance of the GEODB_SVC Xmarc Service running on machine shark registered with the current Service Broker.
This field must be filled in when administering a service which was started with a secret key.
This button, when pressed, displays in the right-hand frame a table giving the state of all (or requested) Xmarc services running under the current Service Broker.If Service Name is omitted, all services are shown. Service Name, and Host:Port may be used to restrict service selection.
An example of Report output, listing all services registered to a Service Broker (running on host anchovy), is given below. You will note that all 3 registered services are running on shark.
Figure 3 Report Button Results
This button, when pressed, displays a state table similar to the Report button, but instructs the Service Broker to connect to each selected Xmarc Service, to ensure it is still running correctly. Any Xmarc Services which have a problem are marked as such in the table.
This button when pressed will stop a currently running service. You will be prompted to confirm the operation. Services are stopped typically for maintenance purposes for software updates etc.
Important: This operation will stop all service instances that are currently registered under the service name.
To stop a "Running" service (or service group) you must first enter the service name into the Service Name edit box and then press the Stop button as shown in Figure 4 below. In this example we are about to stop the GEOLOC service.
Figure 4 Stopping a "Running" service
Once we confirm the stop operation via the popup dialog box, the service(s) is stopped. In actual fact the service instance(s) is terminated. We should then see the status of the particular service set to "Stopped" as shown in Figure 5.
Figure 5 The service is now "Stopped"
This button, when pressed will start a currently stopped service. You will be prompted to confirm the operation.
To start a "Stopped" service (or service group) you must first enter the service name into the Service Name edit box and then press the Start button as shown in Figure 6 below. In this example, we are about to start an FX8I service.
.
Figure 6 Starting a "stopped" service
Once we confirm the operation via the popup dialog box, a new instance of the service is started, the result of which is then displayed as shown in Figure 7.
Figure 7 The service is now "Running"
Important: For Java services, any changes made to the service's property file while the service was in a stopped state will take effect on the re-start.
This button, when pressed, will shut down all selected Xmarc Services by unregistering them with the current Service Broker. You will be asked to confirm the operation.
The Service Broker will send a terminate command to each service in turn. If this fails to terminate the service, the Service Broker will instruct the appropriate Service Agent to kill the process or Java thread.
The unregistration operation removes the services from the Service Broker's service table, with the result that they will not get automatically restarted. To restart them they must be recreated via the New Service button.
Here is an example confirmation screen after the unregistration of all services with the name GEODB_SVC:
Figure 8 Unregister Button Results
This button, when pressed, tidies up the Service Broker's service table, shown by the Check button, and tells the Service Broker to remove any problem services. Where necessary, the Service Broker may ask a Service Agent to abort forcibly a problem service before restarting it.
Confirmation of the clean operation is given by a table similar to that issued by the Report button.
This button, when pressed, will blank out the Service Name, Host Name, Port No. and Secret Key text fields. It performs no other function.
This button, when pressed, will display general help facilities in the right-hand frame of the Service Manager web page.
This button, when pressed, displays in the right-hand frame a table detailing various measurements that are continously monitored throughout the service lifetime.
Here is an example of a Service Metrics report:
Figure 9 Service Metrics Report
The Service Details section contains the various measuements that are monitored during the service's lifetime:
The Service Metrics page is used as an aid to estimating the resources needed on the server tier in order to maintain a particular performance level. For example the table above shows a high Maximum Request Time for the GEOROUTE logical service. This can indicate that the machine hosting the processes may need to be improved (such as faster CPU, more memory etc), or the database server may need to be tuned. If the Queue Request Count is high, then the total number of service instances may need to be increased. If the Queue Request Count is zero however, the current service configuration is effectively handling the client request load.
This button, when pressed will display a dialog in a new browser window allowing a user to reset various counters that are displayed in the Service Metrics page. The dialog, shown in Figure 10, permits the user to identify which counters are to be set back to their reset value. For all but the Instance High Water Mark, the reset value is zero, the Instance High Water Mark counter will be reset to the number of running instances at the time the reset operation is performed.
Figure 10 Reset Metrics Dialog
The user must first identify a service on which the reset operation is to be performed. This is done by entering the service name into the Service Name edit box in the left-hand Frame. Optionally, to further identify a single instance within a logical service group, the hostname:port combination can be added to the Host:Port edit box below the Service Name edit box.
To cancel a reset operation, simply close the dialog window.
This button, when pressed, will display a dialog in the right hand frame for changing the password. This password is used for logging in to the Service Manager.
Example.
Figure 11 Change Password Screen
To create a new service, first ensure that the fields in the left-hand frame of the Service Manager Console reflect the location of the Service Broker to which the service or services are to be registered. The examples we have been using so far show a Service Broker on anchovy.
Then click the New Service button.
Result: The New Service Request Screen appears. (See Figure 12)
Enter the appropriate information in the field sections Agent Location and Service Details, and then click Submit.
Result: The new service, along with other running services, are displayed in a table. (See Figure 13)
Figure 12 New Service Request Screen
As mentioned previously an Xmarc Service is launched via a utility known as a Service Agent. The first field on the New Service Request Screen allows the agent to be selected. This agent will be on the same host as the service to be launched, in our example shark, which happens to be different from the machine hosting the Service Broker (anchovy).
If the required agent is not in the drop down list, this means that the Service Manager does not yet know of its existence. It must first be added to the Service Manager's list of agents via the Agent Administration Screen.
A Service Agent will have a host (the same as that of the Xmarc Service to be launched) and a port, on which it listens for instructions from the Service Broker. The port number, known as the Service Agent Listening Port, must be chosen by the administrator and will be the one assigned to the agent when it was started. Refer to the section Service Agent for more details.
The agent can also have a description associated with it, indicated in parentheses. This allows an administrator to give it a more meaningful name. This description is not relayed to the Service Broker or Service Agent.
The Service Manager will remember all agents and will display them in the drop down list whenever it is subsequently restarted.
These should be the details of the Xmarc Service which we want to launch.
Web Server to Register with: - This field is fixed to the host of the Service Broker shown in the left-hand frame. In our example this is anchovy.
Service Name: - The logical name given to identify one or a collection of services. If the Service Name field in the left-hand frame of the Service Manager Console is non-blank, this name will be used for the field, viz GEODB_SVC.
Service Command: - The name of the executable program that implements the service. In the case of an executable program, this will be the program name with or without the .exe extension. In the case of a Java service, this will be the name of a Java class. In our example we have started a program called fx8i.
Service Start Parameters: - Any command line arguments that the service may need for initialization. In our example, fx8i requires a database connection string -c=scott/tiger.
No. of Services: - The maximum number of services to run concurrently. If the service is already running on the target host (the host of the Service Agent), this will have the effect of changing the maximum number of services which can run on the target host, i.e. the size of the collection or Logical Service. In our example we have set this field to 5.
Service Port No: - The port number that the service will be listening on for client commands sent to it by the service Broker. This field is typically left blank in which case a port number will be allocated by the system. If the service is operating behind a firewall, a port number is typically assigned to the service by the system administrator thereby allowing service communication through the firewall.
Timeouts - The system requires some timeouts to check for failed, busy or possibly hung processes. 3 timeouts are configurable, all measured in seconds:
| Launch | How long the Service Broker should wait before deciding that the service has failed to start, and then cancelling the launch. The agent service or debug logs should tell you the cause of the failure. |
| Queue | When a client request for a service is received by the Service Broker, and all service instances are busy, how long should the broker wait for a service to become available before sending a "service busy" message back to the client. |
| Idle | When a client request is being serviced, how long should the Service Broker wait until deciding that the service instance is hung, at which point the service instance is marked REMOVED and the service instance subsequently killed. The agent service log may indicate the cause of the failure. |
Private Service - Sometimes a service is designed to be for use by internal services only, and not available to external clients. Checking this option will make the service only available to client services registered to the same Service Broker.
Secret Key - Assigning a service a secret key will add an extra layer of protection to a service. Only by supplying the key can it subsequently by stopped or unregistered.
The Service Name, Service Command and No of Services are obligatory fields.
Once the fields have been set, pressing the Submit button will tell the Service Broker to launch the service, via the appropriate Service Agent. The New Service Request Screen will then be replaced by a status table giving the initial result of the launch operation.
Figure 13 New Service Request Screen (after Submit)
Figure 13 shows the results after a New Service Request submission. The URI used in the registration process is shown at the top of the page followed by a table listing the details of all services currently registered to the Service Broker. Note the row for the service identified by the service name: GEODB_SVC has Agents(1/5). This indicates that 1 service instance has been launched from a maximum of 5.
If the row had Agents (0/5) this would have meant that the Service Control Manager had yet to confirm the service was up and running. A further check may be required by pressing the Check button in the left hand frame to confirm the status of the service.
Pressing this button will set all Service Details fields in the New Service Request Screen to default values.
To view the Agent Administration Screen, from the main Services Manager Console, click the Agent Admin button in the left-hand frame.
Result:
Figure 14 Agent Administration Screen
This set of fields enables the list of Service Agents known to the Service Manager to be updated.
By typing an entry into the Add/Modify Agent text field and clicking Add/Change, the agent list may be extended or modified. A Service Agent is known by its host machine and port number on which it listens for commands from the Service Broker. It may also be given a description specified within parentheses for administration purposes. An example can be seen in Figure 14: shark:22003(Geomaps).
An agent can be removed from the list by selecting from the Remove Agent drop-down list and clicking the Remove button.
The Service Manager remembers the agent list between sessions.
Clicking the Report button, displays one or more tables each listing the service instances launched by all agents for the current Service Broker. Agents which have not yet launched any services are not listed.
Figure 15 Agent Administration (Agent Report Screen)
In this example there are 2 agents running, shark:22000 with 2 services, and shark:22003 with one service.
This section of the page enables various attributes of a Service Agent to be administered.
Actions are performed in response to the buttons. A Service Agent must be selected from the pull down list.
Checks whether the Service Agent is running. If successful a confirmation page is displayed. If the Service Agent cannot be contacted, an error page is typically displayed.
Displays the full contents of the Service Agent’s service log. The service log contains messages issued by services launched by the agent. Text is displayed against a pale green background.
If the Number of Lines text field contains a numeric value, this indicates how many lines from the tail of the log are to be displayed. Setting the text field blank displays the whole message log.
Show Debug Log button:
Displays the full contents of the Service Agent’s debug log. The debug log contains messages issued by the Agent itself. Text is displayed against a pale red background.
If the Number of Lines text field contains a numeric value, this indicates how many lines from the tail of the log are to be displayed. Setting the text field blank displays the whole message log.
Displays the value of a Service Agent property. If the Property Name field contains a value, this is the name of the required property. Leaving this field blank will display all Service Agent properties.
Agent properties are discussed in the section Service Agent Installation.
Allows the operator to change the value of a Service Agent property. The fields Property Name and Property Value must be set.
Agent properties are discussed in the section Service Agent Installation.
Allows the operator to monitor the license server to which the Service Agent is connected. The License Server is responsible for allocating license tokens for services which need them to run.
The output is equivalent to that produced by the mxman utility.
To view the Logging Administration Screen, from the Services Manager Console, click the Log Settings button.
Result:
Figure 16 Logging Administration Screen
Logical Service Name: The service name that identifies a service or collection of services to which the logging command is sent. Note that an individual service cannot have its logging level set different to other instances of the Logical Service. This drop-down box will contain all available Logical Services, from which the operator can select.
Logging Level: Choose a level, 0 through to 4. See Figure 16 for details.
When the Submit button is pressed, the current Service Broker communicates with all Xmarc Services with the specified Logical Service Name and sets their message level accordingly.
Messages in the message log can be viewed via the Agent Administration Screen.