# Service Monitor Installation Guide

## Contents
Overview Prerequisites Extracting Service Monitor Setting up the Database Configuring the Service Monitor Database Configuring the Service Monitor TCP Port Configuring the Enterprise Gateway Launching Service Monitor Further Information

## Overview
This topic describes the steps involved in installing and setting up Service Monitor.
## Prerequisites
The prerequisites before installing are as follows: Enterprise Gateway Installation Because Service Monitor reports on transactions processed by the Enterprise Gateway in real-time, the Enterprise Gateway must already be installed. JDBC Database The Enterprise Gateway stores and maintains the monitoring and transaction data read by Service Monitor in a JDBC-compliant database. Service Monitor provides setup scripts for the following databases: MySQL Microsoft SQL Server Oracle IBM DB2
## Extracting Service Monitor
1. Extract the compressed file containing the Service Monitor files to a suitable location. Windows Unzip the Service Monitor zip file to a suitable location. For demonstration purposes, this document assumes that the Service Monitor zip file is extracted to `C:\Oracle`. Linux/Solaris To extract the gzip file, perform the following steps: gunzip the Service Monitor gzip file, for example:
       $gunzip oracleservicemonitor.tar.gz
2. For demonstration purposes, this document assumes that Service Monitor is extracted to `/usr/local/oracle`. Extract the Service Monitor tar archive, for example:
       $tar -xvf oracleservicemonitor.tar
In this document, the location that you extract the Service Monitor application into is referred to as the `INSTALL_DIR`.
## Setting up the Database
Service Monitor reads message metrics from a database and displays this information in a visual format to administrators. This is the same database in which the Enterprise Gateway stores its audit trail and message metrics data. You first need to create this database using the database product of your choice (MySQL, Microsoft SQL Server, Oracle, or IBM DB2). For details on how to do this, see the product documentation for your chosen database. In this document, the example database is named `reports`, but you can use whatever name you wish. When the database is created, you can then set up the relevant database tables. Service Monitor provides SQL scripts to set up the database tables for each of the supported databases. For the purposes of this installation guide, this document assumes that you are using a MySQL database server, and that you have already installed a MySQL database server on the local machine. SQL scripts for setting up the database tables are provided in the `INSTALL_DIR/system/conf/sql` folder in the `/mysql`, `/mssql`, `/oracle`, and `/db2` directories. When you have created the `reports` database, run the SQL commands in the `db_schema.sql` file. Choose the appropriate version of this file from one of the `mssql`, `mysql`, `oracle`, or `db2` folders, depending on the database you intend to store the metrics in. The following example shows the output after creating and setting up the tables in a MySQL database:
    mysql> create database reports;
    Query OK, 1 row affected (0.00 sec)

    mysql> use reports;
    Database changed
    mysql> show tables;
    +-------------------------+
    | Tables_in_reports       |
    +-------------------------+
    | audit_log_points        |
    | audit_log_sign          |
    | audit_message_payload   |
    | metrics_alerts          |
    | metrics_data            |
    | persistent_stat_targets |
    | process_ids             |
    +-------------------------+

    7 rows in set (0.02 sec)
Note: If you wish to use a MySQL database to store message metrics, you can simply copy and paste the contents of the `db_schema.sql` file into the MySQL command prompt (`mysql>`).
## Configuring the Service Monitor Database
By default, Service Monitor is configured to read message metrics from a MySQL database stored on the local machine. Typically, you may wish to use an alternative database, change the password on the default database connection, or add users. To configure the Service Monitor database, perform the following steps: Start the Service Monitor server by running the `servicemonitor` command from the following directory of your Service Monitor installation.
Windows | `Win32\bin`
UNIX\Linux | `posix/bin`
3. In your Policy Studio installation directory, enter the `policystudio` command. On the Policy Studio Home tab, click the following URL to connect to Service Monitor:
       http://HOST:8040/configuration/deployments/DeploymentService
10. where `HOST` points to the IP address or hostname of the machine on which Service Monitor is running. Specify your user name and password details. For more information, see Connection Details. Click Finish. On the Dashboard, double-click the Service Monitor process to load its configuration. Click the External Connections button on the left of the Policy Studio. Expand the Default Database tree node. Right-click the Default Database Connection tree node, and select Edit. The Database Connection dialog enables you to configure the database connection details. By default, the connection is configured to read metrics data from the `reports` database. Edit the details for the Default Database Connection on this dialog, making sure to point to the `reports` database. For example, you should enter a non-default database user name and password:
    Name | Default Database Connection
    URL | `jdbc:mysql://127.0.0.1:3306/reports`
    User Name | `root`
    The following table lists examples of connection URLs for the supported databases, where `reports` is the name of the database and `DB_HOST` is the IP address or host name of the machine on which the database is running:
    Database | Example Connection URL
    Oracle | `jdbc:oracle:thin:@DB_HOST:1521:reports`
    Microsoft SQL Server | `jdbc:sqlserver://DB_HOST:1433;DatabaseName=reports;integratedSecurity=false;`
    MySQL | `jdbc:mysql://DB_HOST:3306/reports`
    IBM DB2 | `jdbc:db2://DB_HOST:50000/reports`
However, in most cases, you may wish to create a new database connection to connect to a database other than the default local database. You can do this by right-clicking Database Connections in the Policy Studio tree view, and selecting Add a Database Connection. For more details on using the Configure Database Connection dialog, see Database Connection. Click the Deploy button in the toolbar. Alternatively, press F6. You can verify that your database connection is configured correctly in the following trace file: `INSTALL_DIR/tracing/Oracle Service Monitor.trc`.
## Configuring the Service Monitor TCP Port
Service Monitor is configured to listen on port `8040` by default. If you have another process already using this port on the machine on which you have installed Service Monitor, you must configure Service Monitor to listen on different port. You can do this in the Policy Studio as follows: Click the Services button at the bottom left of the screen. Expand the Processes -> Service Monitor -> Service Monitor Services node. Right-click the HTTP Interface node identified by the default IP address and port setting (*:8040), and select Edit. In the Configure HTTP Interface dialog, edit the value in the Port field to change the port on which Service Monitor serves reports. For more details, see Configuring HTTP Services.
## Configuring the Enterprise Gateway
This section explains how to configure the Enterprise Gateway to store message metrics in the previously created `reports` database. Connect to the Enterprise Gateway To connect to the Enterprise Gateway in Policy Studio, perform the following steps: Start the Enterprise Gateway by running the `enterprisegateway` command from the following directory of your product installation.
Windows | `Win32\bin`
UNIX\Linux | `posix/bin`
3. On the Policy Studio Home tab, click a server session to make a connection to a server. Specify your connection details (host, port, user name, and password). The default connection URL is:
       http://HOST:8090/configuration/deployments/DeploymentService
3. where `HOST` points to the IP address or hostname of the machine on which the Enterprise Gateway is running. For more information, see Connection Details. Click OK. On the Enterprise Gateway Dashboard, double-click the Enterprise Gateway process to load its configuration. Configure the Database Connection To configure the database connection, perform the following steps: Click the External Connections button on the left of the Policy Studio. Expand the Database Connections tree node. Right-click the Default Database Connection tree node, and select Edit. Configure the database connection to point to the same `reports` database created earlier. For more details, see Configuring the Service Monitor Database. Click OK. Configure Database Logging To configure the database logging settings, perform the following steps: In the Policy Studio tree view, right-click the Oracle Enterprise Gateway process, and select Logging ->Custom. Click Yes. On the Configure Logging dialog, select the Database tab, and select the Enable logging to database checkbox. Select the Default Database Connection from the drop-down if appropriate. Alternatively, select a database connection that you have configured. You must ensure that your database connection points to the same `reports` database created earlier. For more details, see Configuring the Service Monitor Database. Click OK. Configure Monitoring Settings To configure the Enterprise Gateway to monitor traffic and store message metrics in the `reports` database, perform the following steps: Right-click the Oracle Enterprise Gateway process, and select Monitoring -> Metrics. On the Real-time monitoring settings dialog, select the Enable real time monitoring checkbox. In the Reports settings panel, select the Store real time monitoring data for charts/reports checkbox, and specify the following settings:
   Use the following database | Specify the database connection that points to the `reports` database from the drop-down list.
   Time window to store | The time period over which metrics are accumulated and enables you to view messages processed over this interval (for example, the number of messages processed over a 5 second interval).
Click OK. If you wish to enable monitoring of traffic per Enterprise Gateway, right-click the Oracle Enterprise Gateway process, and select Monitoring -> Traffic. In the Traffic Monitor Settings dialog, ensure Enable Traffic Monitor is selected. Click OK. Important Note: Enabling traffic monitoring has a negative impact on performance. If you wish to maximize performance, do not enable these settings. For more details, see Configuring Traffic Monitoring. Deploy to the Enterprise Gateway When you have made these configuration changes, you must deploy them to the Enterprise Gateway. To do this, select Settings -> Deploy from the Policy Studio main menu. Alternatively, click the Deploy button in the toolbar, or press F6. The Enterprise Gateway now sends both audit trail and message metrics data to the `reports` database. This database is then queried by Service Monitor to produce reports showing system health, service usage, clients, message size and volume, and so on. It is important to note that the Monitoring Settings configured here are process-wide. You can also configure an HTTP Services Group to send metrics data to the database selected at the process level. To do this, right-click the HTTP Services Group (for example, Default Services), and select Edit. To monitor traffic in this Group, ensure that the Include in real-time monitoring checkbox is selected. Similarly, you can disable monitoring for this Group by unselecting this checkbox. Verify your Database Connection Settings You can verify that your database connection is configured correctly in the `INSTALL_DIR/tracing/Oracle Enterprise Gateway.trc` file. For more details on tracing, see Troubleshooting.
## Launching Service Monitor
2. To launch Service Monitor, perform the following steps: Start Service Monitor using the `servicemonitor` script, in the `/bin` directory of your Service Monitor installation. Using the default port, you can connect to the Service Monitor interface in a browser at the following URL:
       http://HOST:8040/
where `HOST` points to the IP address or hostname of the machine on which Service Monitor is installed. Log in using the default `admin` user with password `changeme`. You can edit this user in Policy Studio using the Users interface from the Policy Studio tree view. Note: Service Monitor produces reports based on message metrics that are stored by the Enterprise Gateway when processing XML messages. To produce a graph that shows the number of connections made by the Enterprise Gateway to a particular Web Service, you must first set up a policy that routes messages to that Web Service. When this policy has been configured, you must send some messages through this policy so that they are routed on to the target Web Service. In addition, if you change from using an existing database with remote hosts/clients configured to another database with a different set of remote hosts/clients configured, you must restart both the Enterprise Gateway and Service Monitor.
## Further Information
For more details on using Policy Studio management features, see Getting Started with Managing Deployments. For more details on viewing real-time monitoring and transaction data using Service Monitor, see the Service Monitor User Guide.