Service Manager Console

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

 

Service Broker Definition

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.

Service Broker

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.

Web Server

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.

Servlet Path

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.

Agent Admin Button

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.

New Service Button

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.

Log Settings Button

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.

 

Xmarc Service Definition

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

Logical Services

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.

Service Name

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.

Host:Port

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.

Secret Key

This field must be filled in when administering a service which was started with a secret key.

Report Button

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

Check Button

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.

Stop Button

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"

Start Button

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.

Unregister Button

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

Clean Button

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.

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

Help Button

This button, when pressed, will display general help facilities in the right-hand frame of the Service Manager web page.

Monitoring Details Button

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:

  1. Service Duration: displays the total time that a particular service instance has been running.
  2. Instance Hit Count: displays the number of client requests that have been directed by the Broker to a particular service instance.
  3. Maximum Request Time: displays the maximum time taken by a service instance to answer the request.
  4. Queue Request Count: displays the number of client requests that have been placed in a particular service instance's queue waiting to be serviced.
  5. Maximum Queue Time: displays the maximum time a request has had to wait in a particular service instance's queue before being serviced.
  6. Instance High Water Mark: displays the maximum number of service instances that have been started by the Broker in order to handle the client request load.

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.

Reset Button

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.

Change Password Button

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

 

New Service Request

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

Agent Location

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.

Service Details

These should be the details of the Xmarc Service which we want to launch.

The Service Name, Service Command and No of Services are obligatory fields.

Submit Button

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.

Clear Fields Button

Pressing this button will set all Service Details fields in the New Service Request Screen to default values.

 

Agent Administration

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

Agent List

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.

Agent Reports

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.

Agent Properties

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.

Show Status button:

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.

Show Service Log button:

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.

Get Property button:

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.

Set Property button:

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.

Show License Status button:

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.

 

Logging Administration Screen

To view the Logging Administration Screen, from the Services Manager Console, click the Log Settings button.

Result:

Figure 16 Logging Administration Screen

Logging Administration Screen Fields

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.


Previous Chapter   Next Chapter