Logging Configuration

Contents

Overview

One of the most important features of a server-based product is its ability to maintain highly detailed and configurable logging. It is crucial that a record of each and every transaction is kept, and that these records can easily be queried by an administrator to carry out detailed transaction analysis. In recognition of this requirement, the Enterprise Gateway provides detailed logging to a number of possible locations.

You can configure the Enterprise Gateway so that it logs information about all requests. Such information includes the request itself, the time of the request, where the request was routed to, and the response that was returned to the client. The logging information can be written to the console, log file, local/remote syslog, and/or a database, depending on what is configured in the Configure Logging dialog.

The Enterprise Gateway can also digitally sign the logging information it sends to the log files and the database. This means that the logging information can not be altered after it has been signed, thus enabling an irreversible audit trail to be created.

Configuring Log Output

To edit the default logging settings that ship with the Enterprise Gateway, in the Policy Studio main menu, select Settings -> Settings -> Default Logging Settings. Alternatively, in the toolbar, click the drop-down option on the Settings button, and select Default Logging Settings.

In addition, at the Process level, you can override the default log settings by right-clicking the Process in the Policy Studio tree, and selecting Logging -> Custom.

Whether editing or customizing the default logging settings, you can use the Configure Logging tabbed dialog to configure the Enterprise Gateway to log to the following locations.

Log to Text File

To configure the Enterprise Gateway to log in text format to a file, click the Text File tab, and select the Enable logging to file checkbox. You can configure the following fields:

  • File Name:
    Enter the name of the text-based file that the Enterprise Gateway logs to. By default, the log file is called oracle.
  • File Extension:
    Enter the file extension of the log file in this field. By default, this has a .log extension.
  • Directory:
    Enter the directory of the log file in this field. By default, all log files are stored in the /logs directory of your Enterprise Gateway installation.
  • File Size:
    Enter the maximum size that the log file grows to. When the file reaches the specified limit, a new log file is created. By default, the maximum file size is 1000 kilobytes.
  • Roll Log Daily:
    Specify whether to roll over the log file at the start of each day. This is enabled by default.
  • Number of Files:
    Specify the number of log files that are stored. The default number is 20.
  • Format:
    You can specify the format of the logging output using the values entered here. You can use properties to output logging information that is specific to the request. The default logging format is as follows, with descriptions of the available logging properties below: 

    ${level} ${timestamp} ${id} ${text} ${filterType} ${filterName}

    • level:
      The log level (fatal, fail, success).
    • timestamp:
      The time that the message was processed in user-readable form.
    • id:
      The unique transaction ID assigned to the message.
    • text:
      The text of the log message that was configured in the filter itself. In the case of the Log Message Payload filter, the ${payload} property contains the message that was sent by the client.
    • filterName:
      The name of the filter that generated the log message.
    • filterType:
      The type of the filter that logged the message.
    • ip:
      The IP address of the client that sent the request.
  • Signing Key:
    To sign the log file, select a Signing Key from the Certificates Store that is used in the signing process. By signing the log files, you can verify their integrity at a later stage.

Log to XML File

To configure the Enterprise Gateway to log to an XML file, click the XML File tab, and select the Enable logging to XML file checkbox.

The log entries are written as the values of XML elements in this file. You can view historical XML log files (not the current file) as HTML for convenience by opening the XML file in your default browser. The /logs/xsl/MessageLog.xsl stylesheet is used to render the XML log entries in a more user-friendly HTML format.

You can configure the following fields on the XML File tab:

  • File Name:
    Enter the name of the text-based file that the Enterprise Gateway logs to. By default, the log file is called oracle.
  • File Extension:
    Enter the file extension of the log file in this field. By default, the log file is given the .log extension.
  • Directory:
    Enter the directory of the log file in this field. By default, all log files are stored in the /logs directory of your Enterprise Gateway installation.
  • File Size:
    Enter the maximum size that the log file grows to. When the file reaches the specified limit, a new log file is created. By default, the maximum file size is 1000 kilobytes.
  • Roll Log Daily:
    Specify whether to roll over the log file at the start of each day. This is enabled by default.
  • Number of Files:
    Specify the number of log files that are persisted. The default number is 20.
  • Signing Key:
    To sign the log file, select a Signing Key from the Certificates Store that will be used in the signing process. By signing the log files, you can verify their integrity at a later stage.

Log to Database

Using this option, you can configure the Enterprise Gateway to log messages to an Oracle, SQL Server, or MySQL relational database. Before configuring the Enterprise Gateway to log to a database, you must first create the tables that the Enterprise Gateway writes to. The SQL commands required to set up these tables for each of these databases can be found under the INSTALL_DIR/system/conf/sql. This folder contains a directory for each of the Oracle, SQL Server, and MySQL databases, each of which contains the appropriate SQL scripts.

The SQL commands to generate the database table can be found in the audit_trail.sql file. Select this file from the appropriate directory (depending on your database), and use the tool of your choice to run the SQL commands contained in the file. For example, to create the logging tables in a MySQL database, you can simply copy and paste the SQL commands into the MySQL command prompt.

When you have set up the logging database tables, you can configure the Enterprise Gateway to log to the database. To do this, click the Database tab on the Configure Logging dialog, and select the Enable logging to database checkbox. You can configure the following fields on the Database tab:

  • Connection:
    Select an existing database from the Connection drop-down list. To add a database connection, click the External Connections button on the left, right-click the Database Connections tree node, and select Add a Database Connection. For more details, see the Database Connection topic.
  • Signing Key:
    You can sign log messages stored in the database to ensure that they are not tampered with. Click the Signing Key button to open the list of certificates in the Certificate Store. You can then select the key to use to sign log messages.

Log to Local Syslog

To configure the Enterprise Gateway to send logging information to the local UNIX syslog, click the Local Syslog tab, and select the Enable logging to local UNIX Syslog checkbox. You can configure the following fields:

  • Facility:
    Select the local syslog facility that the Enterprise Gateway should log to. The default is LOCAL0.
  • Format:
    You can specify the format of the log message using the values (including properties) entered in this field. For details on the properties that are available, see Log to Text File.

Log to Remote Syslog

To configure the Enterprise Gateway to send logging information to a remote syslog, click the Remote Syslog tab, and select the Enable logging to Remote Syslog checkbox. You can configure the following fields:

  • Syslog Server
    Select a previously configured Syslog Server from the drop-down list.
  • Format:
    You can specify the format of the log message using the values (including properties) entered in this field. For details on the properties that are available, see Log to Text File.

Log to System Console

To configure the Enterprise Gateway to send logging information to the system console, click the System Console tab, and select the Enable logging to system console checkbox. For details on how to use the Format field to configure the format of the log message, see Log to Text File.