Configure Runtime Session Logging

The Runtime stores session execution information in a log database.

The log database is by default an H2 database built in the runtime, which provides ready-to-use configuration.

For production environments, we recommend using a dedicated database storage, using for example in a Oracle, Microsoft SQL Server (MSSQL), etc dedicated database. See Certified Database Servers.

Configure Session Logging

To configure the runtime log storage:

  1. Edit the engineParameters.xml file.

  2. Configure the logging and the log database parameters as explained below.

  3. Restart the runtime or reinstall the runtime service.

Configuration Example

The following configuration example uses a log database named logDatabase, configured to use the runtime built-in H2 database.

The built-in H2 database is, by default, only accessible from the runtime itself, and is NOT recommended for production use. See Built-in H2 database. 
<parameters>
  <...>
  <engineParameters>
    <...>
      <parameter name="userLogDefaultName"
        value="logDatabase"/>
      <parameter name="defaultSessionLogLevel"
        value="400"/>
      <...>
  </engineParameters>
  <...>
  <logs>
    <...>
      <log userLogName="logDatabase"
        autoUpdate="true"
        userLogClass="com.semarchy.xdi.runtime.sessionlog.RdbmsLogger">
        <parameter name="userLogRdbmsDriver"
          value="org.h2.Driver"/>
        <parameter name="userLogRdbmsUrl"
          value="jdbc:h2:file:sessions/internalDb/sessionLogs"/>
        <parameter name="userLogRdbmsUser"
          value="backend-user"/>
        <parameter name="userLogRdbmsPassword"
          value="backend-password"/>
        <!-- Use the following paramater to specify an encrypted password. -->
        <!--<parameter name="userLogRdbmsEncryptedPassword"
        value=""/>-->
        <parameter name="userLogRdbmsModule"
          value="internal"/>
        <parameter name="userLogRdbmsVarcharType"
          value="varchar"/>
        <parameter name="userLogRdbmsVarcharMaxSize"
          value="1000"/>
        <parameter name="userLogRdbmsNumericType"
          value="numeric"/>
        <parameter name="userLogRdbmsClobType"
          value="clob"/>
        <parameter name="userLogRdbmsBlobType"
          value="blob"/>
        <parameter name="userLogRdbmsSchemaName"
          value="logs"/>
        <parameter name="userLogRdbmsUseSchemaNameForIndexCreation"
          value="true"/>
        <parameter name="userLogRdbmsDeleteSyntaxe"
          value="Delete from"/>
        <!--<parameter name="userLogRdbmsTablePrefix"
          value="SEM_RT_LOG_"/>-->
        <parameter name="userLogRdbmsCompressedLevel"
          value="bestCompression"/>
        <!-- bestCompression / bestSpeed / default-->
        <parameter name="userLogRdbmsDeliveryFormat"
          value="compressed"/>
        <!-- text / binary / compressed-->
        <parameter name="userLogRdbmsPropertyMaxVarcharSize"
          value="1000"/>
        <!-- -1 : infinite -->
        <parameter name="userLogRdbmsPropertyMaxClobSize"
          value="10000"/>
        <parameter name="userLogRdbmsPropertyBinaryFormat"
          value="compressed"/>
        <!-- binary / compressed-->
        <parameter name="userLogRdbmsTimestampQuery"
          value="select now()"/>
        <parameter name="userLogRdbmsInactivityDetectionPeriod"
          value="90000"/>
        <parameter name="userLogRdbmsActivityRefreshInterval"
          value="60000"/>
        <parameter name="userLogRdbmsDeletionWithNotExists"
          value="true"/>
        <!--<parameter name="userLogRdbmsIndexCreationOption"
          value=""/>-->
        <!--<parameter name="userLogRdbmsTableCreationOption"
          value=""/>-->
        <parameter name="userLogRdbmsPoolEnabled"
          value="true"/>
        <parameter name="userLogRdbmsPoolConnectionTimeout"
          value="30000"/>
        <parameter name="userLogRdbmsPoolIdleTimeout"
          value="600000"/>
        <parameter name="userLogRdbmsPoolKeepAliveTime"
          value="0"/>
        <parameter name="userLogRdbmsPoolMaxLifetime"
          value="1800000"/>
        <parameter name="userLogRdbmsPoolMinimumIdle"
          value="0"/>
        <parameter name="userLogRdbmsPoolMaximumSize"
          value="20"/>
        <parameter name="userLogRdbmsPoolValidationTimeout"
          value="5000"/>
      </log>
      <...>
  </logs>
  <...>
</parameters>

Logging Configuration

In the engine parameters, the following parameters configure the logging:

  • The userLogDefaultName parameter defines the database configuration used for logging. A corresponding log database configuration must exist under the <logs> node.

  • The defaultSessionLogLevel parameter defines the default log level for the sessions. A higher value means that more information is logged. Possible values are: –1, 0, 100, 200, 300, 400. The

The defaultSessionLogLevel only applies to sessions for which the log level is not specifically defined.
Example 1. Sample Logging Configuration
  <engineParameters>
    <...>
    <parameter name="userLogDefaultName" value="logDatabase"/>
    <parameter name="defaultSessionLogLevel" value="400"/>
    <...>
  </engineParameters>
Refer to the runtime parameters reference for detailed information about each parameter.

Log Database Configuration

A log database configuration contains the connection information to a database that hosts the log. The log database used by the runtime is the one for which the userLogName property matches the userLogDefaultName engine parameter.

In the example below, the runtime logs into the productionLogDatabase database.

<engineParameters>
  <...>
  <parameter name="userLogDefaultName" value="productionLogDatabase"/> (1)
  <...>
</engineParameters>
  <...>
  <logs>
  <...>
    <log userLogName="productionLogDatabase" autoUpdate="true" userLogClass="com.semarchy.xdi.runtime.sessionlog.RdbmsLogger"> (2)
    <parameter name="userLogRdbmsDriver" value="oracle.jdbc.driver.OracleDriver"/>
    <parameter name="userLogRdbmsUrl" value="jdbc:oracle:thin:@prod001.acme.com:1521:ORA"/>
  <...>
1 The log database used is productionLogDatabase.
2 The productionLogDatabase log database configuration, using an Oracle storage.
You do not need to configure anything specific in the dedicated database storage. All the necessary tables will be created automatically the first time the runtime connects to this database storage.
For the Runtime to communicate with a database other than the built-in H2 database, you must define in the log database configuration’s userLogRdbmsModule parameter the name of the module containing the required JDBC database drivers.
The default engineParameters.xml installed with the runtime contains commented log database configuration samples. Uncomment and adapt these samples to configure to your log storage. Make sure to set the userLogDefaultName engine parameter to the right log database configuration.

Log Database Configuration Example

The following configuration example uses a log database named oracleLogDatabase using an Oracle storage.

The following parameters must be adapted to the database used.

  • userLogRdbmsUrl

  • userLogRdbmsUser

  • userLogRdbmsPassword

  • userLogSchemaName

  • userLogRdbmsModule

Refer to the runtime parameters reference for detailed information about each parameter. 
<parameters>
  <...>
  <engineParameters>
  <...>
    <parameter name="userLogDefaultName"
      value="oracleLogDatabase"/>
    <parameter name="defaultSessionLogLevel"
      value="400"/>
    <...>
  </engineParameters>
  <...>
  <logs>
    <...>
    <log userLogName="oracleLogDatabase"
      autoUpdate="true"
      userLogClass="com.semarchy.xdi.runtime.sessionlog.RdbmsLogger">
      <parameter name="userLogRdbmsDriver"
        value="oracle.jdbc.driver.OracleDriver"/>
      <parameter name="userLogRdbmsUrl"
        value="jdbc:oracle:thin:@[host]:[port]:[sid]"/>
      <parameter name="userLogRdbmsUser"
        value="[USER]"/>
      <parameter name="userLogRdbmsPassword"
        value="[PASSWORD]"/>
      <parameter name="userLogRdbmsModule"
        value="[MODULE_NAME]"/>
      <parameter name="userLogRdbmsSchemaName"
        value="[SCHEMA_NAME]"/>
      <parameter name="userLogRdbmsVarcharType"
        value="varchar2"/>
      <parameter name="userLogRdbmsVarcharMaxSize"
        value="4000"/>
      <parameter name="userLogRdbmsClobType"
        value="clob"/>
      <parameter name="userLogRdbmsBlobType"
        value="blob"/>
      <parameter name="userLogRdbmsNumericType"
        value="number"/>
      <parameter name="userLogRdbmsDeleteSyntaxe"
        value="Delete from"/>
      <parameter name="userLogRdbmsDeliveryFormat"
        value="text"/>
      <parameter name="userLogRdbmsPropertyMaxVarcharSize"
        value="1000"/>
      <parameter name="userLogRdbmsPropertyMaxClobSize"
        value="10000"/>
      <parameter name="userLogRdbmsPropertyBinaryFormat"
        value="compressed"/>
      <parameter name="userLogRdbmsPoolEnabled"
        value="true"/>
      <parameter name="userLogRdbmsPoolConnectionTimeout"
        value="30000"/>
      <parameter name="userLogRdbmsPoolIdleTimeout"
        value="600000"/>
      <parameter name="userLogRdbmsPoolKeepAliveTime"
        value="0"/>
      <parameter name="userLogRdbmsPoolMaxLifetime"
        value="1800000"/>
      <parameter name="userLogRdbmsPoolMinimumIdle"
        value="0"/>
      <parameter name="userLogRdbmsPoolMaximumSize"
        value="20"/>
      <parameter name="userLogRdbmsPoolValidationTimeout"
        value="5000"/>
    </log>
    <...>
  </logs>
  <...>
</parameters>

Disable Session Logging

You have two options to disable session logging in the runtime:

  • Do not define a Log Database Configuration configuration file: Remove or comment all configurations under the <logs> node. By default, without a valid log database configuration, the runtime will not log for the sessions.

  • You can also explicitly define a specific log database using the EmptyLogger class as shown below. This method is recommended.

Example 2. Configure the runtime for no logging
<parameters>
  <...>
  <engineParameters>
    <...>
    <parameter name="userLogDefaultName" value="noLogs"/>
    <...>
  </engineParameters>
  <...>
  <logs>
    <log
    userLogName="noLogs"
    autoUpdate="false"
    userLogClass="com.semarchy.xdi.runtime.sessionlog.EmptyLogger">
    </log>
  </logs>
  <...>
</parameters>

Scheduled Log Purges

You can schedule automatic purges of the session logs, in Semarchy xDI Production Analytics in the Purge tab of the Runtime Editor or using the command line as explained below.

To schedule a log purge:

  1. Run the startCommand.bat|sh script.

  2. Run the schedule purge command described below

schedule purge keep <number> <minute|hour|day|session>  cron <cronExpression> [sessionname <name,name2,...>] [status <done,error,killed>] [on host <hostname>] [port <hostport>]

For example:

schedule purge keep 90 day cron "0 0 23 * * ?"

Debug Logs

The runtime also stores debug logs in the log/ sub-directory of its installation folder.
By default, the debug logs are rotating to keep a reasonable volume of debug logs.

These logs are configured using the log4j.xml file.

You may want to configure the debug logs to troubleshoot issues with the help of the Semarchy support team.

Appendix

Built-in H2 database

Summary

The runtime ships a built-in H2 database that is used with the default configuration for the log database and scheduler database.

The built-in H2 database is, by default, only accessible from the runtime itself, and is NOT recommended for production use.

For production use, we recommend using the Certified Database Servers.

Database Configuration

The built-in H2 database is created at the first runtime’s startup, with the user and password defined in the runtime’s configuration file. See Configuration Example.

If you start the runtime with an already existing database, make sure that the user and password defined in the runtime configuration match the user and password expected by the database. This is most notably important when upgrading from a previous runtime version.

On runtime versions prior to 2023.1.4, the built-in H2 database was created by default with the user sa and no password. Define the log configuration and scheduler configuration to these if you are using such a database.

Open external access

As mentioned previously, the built-in H2 database is, by default, only accessible from the runtime itself. The runtime logs into the database in memory, and it isn’t exposed as a server accessible from the outside.

To open access to the built-in H2 database from the outside, it must be manually started as a server. This can be useful to access the sessions logs from Semarchy xDI Production Analytics, for example. To do this:

  1. Stop the runtime.

  2. Update the runtime configuration

    1. Log Database:

      1. Change the userLogRdbmsUrl parameter value from jdbc:h2:file:sessions/internalDb/sessionLogs to jdbc:h2:tcp://localhost:42100/sessions/internalDb/sessionLogs

    2. Scheduler:

      1. Change the org.quartz.dataSource.database01.URL parameter value from jdbc:h2:file:scheduler/internalDb;SCHEMA=SCHEDULER to jdbc:h2:tcp://localhost:42100/scheduler/internalDb;SCHEMA=SCHEDULER

  3. Start the built-in H2 database as a server.

    1. According to your operating system, run the start-database.bat or start-database.sh from the runtime’s installation root folder.

  4. Start the runtime.

After this change, the runtime requires the built-in H2 database server to be running prior to being started. Make sure to start the built-in H2 database prior to the runtime.
As you used the "start-database.bat" or "start-database.sh" script to start the built-in H2 database as a server, you can use the "stop-database.bat" or "stop-database.sh" script to stop it. You can find these scripts from the runtime’s installation root folder.