About BIRT iHub usage and error log consolidator
The log consolidator application is a Java application that reads data from an BIRT iHub usage or error log file and uses JDBC to add the information to a database. In an BIRT iHub cluster, you must install and run the log consolidator application on each BIRT iHub node to consolidate the cluster’s usage and error log information in a database. Before running the log consolidator application, you must install the following components:
BIRT iHub
Log consolidator application files
Log consolidator configuration file
Database used by the log consolidator application
BIRT iHub installs the required JAR files for the log consolidator application in $ACTUATE_HOME/Jar/UsageAndErrorConsolidator. These files include:
usageanderrorconsolidator.jar
The com.actuate.consolidator application class and properties files.
Java Architecture for XML Binding (JAXB) JAR files
JAXB provides a framework that supports run-time mapping between XML and Java objects.
ojdbc14.jar
The supported Oracle JDBC Driver. The reference implementation uses Oracle as the example database.
naming-java.jar
Contains the handler for the Java namespace.
The log consolidator application also uses the following Microsoft Windows Registry keys or UNIX environment variables set by the BIRT iHub installation process:
On Windows, make sure the following registry keys exist:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Actuate\Common\22.0
\AC_JAVA_HOME
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Actuate\Common\22.0
\AC_JRE_HOME
On a machine running any of the Release 11 versions of Actuate iServer System, the location of the AC_JAVA_HOME and AC_JRE_HOME registry keys is:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Actuate\Common\11.0
The log consolidator application uses java.exe from:
AC_JRE_HOME\bin
On UNIX, make sure the following environment variables exist:
AC_JAVA_HOME
AC_JRE_HOME
The log consolidator application uses java.exe from:
$AC_JRE_HOME/bin
In BIRT iHub Integration Technology, the UsageAndErrorConsolidator directory contains additional files that you must use to complete the installation of the log consolidator application:
/DBScripts contains the SQL script, CreateActuateLogTables.sql, which creates the tables in the Oracle database used by the Actuate log consolidator sample application. A readme.txt file describes this SQL script file.
/jar contains the JAR files required by the log consolidator application.
/Setup contains the following files that startup and shutdown the log consolidator application:
consolidatorconfig.xml is the sample consolidator configuration file that specifies settings such as the following items:
Database driver, URL, encoding, schema, user name, and password
Usage and error log details, such as the file names, refresh interval, number of logs, and whether a log file is enabled
The UNIX version uses the scripts, start_consolidator.sh and stop_consolidator.sh, to start up and shut down the log consolidator application.
The Windows version uses a setup application, consolidatorwin.exe, that installs the log consolidator application as a Windows service and starts and stops the application.
A readme.txt file describes how to use these components.
/src contains the following items:
usageanderrorconsolidator.jar, the JAR file for the log consolidator application
consolidatormake.xml, an Ant build file
com.actuate.consolidator, the log application source code
How to install the log consolidator application
1 Edit the following settings in consolidatorconfig.xml:
JDBC driver name
URL, specifying the type of JDBC driver and database connection information, including host name, port, and database instance (SID) or service name, using the following syntax:
jdbc:oracle:thin:@//[HOST][:PORT][:SID/SERVICE]
Database login information, including schema, user name and password
Refresh interval
Measured in seconds. The default value is 10 seconds.
You may need to change the refresh interval depending on the amount of logging your system performs. The log consolidator application commits transactions to the database every 10 seconds or when the number of transactions exceeds 80, whichever occurs first.
Usage and error log settings:
Log file names
Number of log files for each type of file
The log file names and number of files must match the actual BIRT iHub configuration.
If you change a BIRT iHub setting, you must also change the corresponding consolidator configuration setting and restart BIRT iHub and the log consolidator application.
The following code example shows the default settings for consolidatorconfig.xml:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LogConsolidator>
<Database>
<DriverName>oracle.jdbc.OracleDriver</DriverName>
<URL>jdbc:oracle:thin:@dbsrv4-w2k:1521:Oran9i</URL>
<Encoding>UTF8</Encoding>
<Schema>Users</Schema>
<DatabasePropertyList>
<Properties>
<Name>UserName</Name>
<Value>actest</Value>
</Properties>
<Properties>
<Name>Password</Name>
<Value>systest</Value>
</Properties>
</DatabasePropertyList>
</Database>
<Consolidator>
<RefreshInterval>10</RefreshInterval>
<UsageLogEnabled>true</UsageLogEnabled>
<ErrorLogEnabled>false</ErrorLogEnabled>
<UsageLogProperties>
<LogFileName>usage_log</LogFileName>
<NumberOfLogFiles>2</NumberOfLogFiles>
</UsageLogProperties>
<ErrorLogProperties>
<LogFileName>error_log</LogFileName>
<NumberOfLogFiles>2</NumberOfLogFiles>
</ErrorLogProperties>
</Consolidator>
</LogConsolidator>
2 Copy the configuration file, consolidatorconfig.xml, to the following BIRT iHub directory:
$AC_SERVER_HOME/etc
3 Install and run the startup and shutdown files after setting up the database:
On a UNIX system, the following Actuate scripts start and stop the consolidator application:
start_consolidator.sh
Starts the log consolidator application. The script takes $AC_SERVER_HOME as an argument and uses it to set the following path variables:
Configuration file
JAR file directory
CLASSPATH
The script stores the process ID or PID in $AC_SERVER_HOME/etc/consolidator.pid. Add this script to BIRT iHub script start_srvr.sh to start the consolidator application whenever you start BIRT iHub. start_consolidator.sh attempts to start the application five times.
stop_consolidator.sh
Stops the log consolidator application. The script takes $AC_SERVER_HOME as an argument and uses it to read the log consolidator application PID from $AC_SERVER_HOME/etc/consolidator.pid and kills the process. Add this script to BIRT iHub script stop_srvr.sh to stop the consolidator application whenever you stop the BIRT iHub.
On a Windows system, the consolidatorwin.exe utility installs and removes the application as a Windows service, and starts and stops the consolidator application. The BIRT iHub installation process installs and runs the utility in the following directory:
$AC_SERVER_HOME\bin
Use the consolidator.exe utility to install and configure the consolidator application. This utility assumes it is running in the BIRT iHub \bin directory.
The consolidatorwin.exe utility supports the following command line syntax:
consolidatorwin [-H/-?] [-SserviceType] [-UuserName] [-Ppassword]
The command-line arguments specify the following options:
-H requests help on usage
-S specifies the following types of service:
auto adds the log consolidator as the Actuate Usage and Error Logging Consolidator 9 service that starts automatically when Windows restarts.
manual adds the log consolidator as the Actuate Usage and Error Logging Consolidator 9 service that requires manual startup when Windows restarts.
console starts the consolidator at a Windows command prompt.
remove stops the service.
-U specifies the username
The Windows user starting the consolidator application. Actuate recommends using the same user as the user that starts BIRT iHub.
-P specifies the password
The user password.
The following command adds the consolidator application as a Windows service that starts automatically when Windows starts:
consolidatorwin -Sauto -UUsername -PPassword
How to configure the log consolidator database
1 Configure a database server machine, Oracle server, and database.
2 Using Oracle SQL*Plus, log in as the system database administrator.
3 Run the CreateActuateLogTables.sql script.
The following command runs the CreateActuateLogTables.sql script from the install folder in the BIRT iHub Integration Technology installation for Windows:
SQL> @"C:\<BIRT iHub Integration Technology install folder>
\ServerIntTech\UsageAndErrorConsolidator\DBScripts\CreateActuateLogTables.sql";
CreateActuateLogTables.sql drops the ActuateLog and ActuateLogUser users, performs cascading deletes on all their objects, including sequences, tables, and indexes, and recreates these objects. The script creates the following database objects:
Tables to contain the usage and error log data
INSERT statements add predefined codes and descriptions for the event, file, job, object, operation, output format, service, and status types, after creating the tables.
Sequence generators to provide the values for usage and error event IDs when inserting log data
Each usage and error event ID is a unique value.
Indexes to contain primary and foreign key columns in the tables:
Primary key constraints on columns containing predefined codes ensure that these values are unique and not null.
Foreign key references on columns containing predefined codes ensure that these values are consistent with the values in the primary keys.
The ActuateLog schema contains the following tables and indexes:
AcAdminEvent
Contains the log records for administration operation events, including the following data:
Event ID
Object type code, indicating a User, Role, Channel, Group, File, or Folder object
Object operation code, indicating a Create, Delete, Modify, Login, Logout, or Download operation
Object name, version name, size, and attribute
Old and new values
Table 30‑7 shows the structure of the AcAdminEvent table.
Table 30‑7 Structure of the AcAdminEvent table
Column | Data type | Constraint | References | Key |
EventId | INTEGER | AcApEv _AdEvId _Idx | AcEvent .EventId | Primary |
ObjectTypeCode | INTEGER | | AcObject Type .Object TypeCode | |
ObjectOperationCode | INTEGER | | AcObject Operation .Object Operation Code | |
ObjectName | VARCHAR2(1000) | | | |
ObjectVersionName | VARCHAR2(255) | | | |
ObjectSize | INTEGER | | | |
ObjectAttribute | VARCHAR2(50) | | | |
OldValue | VARCHAR2(2000) | | | |
NewValue | VARCHAR2(2000) | | | |
AcApplicationEvent
Contains the log records for application events, including the following data:
Event ID
Executable name
Executable version, indicating an RPTDOCUMENT, RPTDESIGN, or other file type
Job type code, indicating an Async, Persistent, and Transient job type
Resource group ID
Dispatch node, indicating the volume, system, and server
Output format code, indicating PDF, XLS, HTML, or other output format
Table 30‑8 shows the structure of the AcApplicationEvent table.
Table 30‑8 Structure of the AcApplicationEvent table
Column | Data type | Constraint | References | Key |
EventId | INTEGER | AcApEv _ApEvId _Idx | AcEvent .EventId | Primary |
ExecutableName | VARCHAR2(1000) | | | |
ExecutableVersion | VARCHAR2(100) | | AcFileType .FileTypeCode | |
FileTypeCode | INTEGER | | | |
Parameters | VARCHAR2(2000) | | | |
JobName | VARCHAR2(100) | | | |
JobTypeCode | INTEGER | | AcJobType .JobTypeCode | |
JobSubmittedTimestamp | DATE | | | |
ResourceGroupId | INTEGER | | AcResource Group .Resource GroupId | |
DispatchNode | INTEGER | | AcSystem Component .System ComponentId | |
RequestId | VARCHAR2(100) | | | |
RequestWaitTime | INTEGER | | | |
RequestRunningTime | INTEGER | | | |
OutputName | VARCHAR2(1000) | | | |
OutputVersion | VARCHAR2(100) | | | |
OutputFormatCode | INTEGER | | AcOutput Format .Output Format Code | |
OutputSize | INTEGER | | | |
PageCount | INTEGER | | | |
PageNumbersViewed | VARCHAR2(50) | | | |
AcErrorEvent
Contains the log records for error events, including the following data:
Error event ID
System component ID, indicating the volume, system, and server
User name
Error code, category, severity, parameters, and message
Table 30‑9 shows the structure of the AcErrorEvent table.
Table 30‑9 Structure of the AcErrorEvent table
Column | Data type | Constraint | References | Key |
ErrorEventId | INTEGER | AcErEv_ErEvId _Idx | AcEvent .EventId | Primary |
EventTimestamp | DATE | | | |
SystemComponentId | INTEGER | | AcSystem Component .System ComponentId | |
UserName | VARCHAR2(255) | | | |
ErrorCode | INTEGER | | | |
ErrorCategory | VARCHAR2(255) | | | |
ErrorSeverity | INTEGER | | | |
ErrorParameter1 | VARCHAR2(50) | | | |
ErrorParameter2 | VARCHAR2(50) | | | |
ErrorParameter3 | VARCHAR2(50) | | | |
ErrorMessage | VARCHAR2(255) | | | |
AcErrorLogOffset
Contains the following error log data:
File offsets
Volume names
Last update timestamp
Table 30‑10 shows the structure of the AcErrorLogOffset table.
Table 30‑10 Structure of the AcErrorLogOffset type
Column | Data type/Values | Constraint | References | Key |
FileIndex | NUMBER | | | |
FileOffset | NUMBER | | | |
VolumeName | VARCHAR2(50) | NOT NULL | | Primary |
LastUpdateTimeStamp | NUMBER | | | |
AcEvent
Contains the log records for events, including the following data:
Event ID
Event timestamp
System component ID, indicating the volume, system, and server
Event type code, indicating a Generate, Print, View, Delete, Admin, Query, or Search event type
Start and end timestamps
Status code, indicating Success or Failure
Service type code, indicating a Factory, View, Encyclopedia, Integration, or Cache service type
Table 30‑11 Structure of the AcEvent table
Column | Data type | Constraint | References | Key |
EventId | INTEGER | AcSt_StCo_Idx | | Primary |
EventTimestamp | DATE | | | |
SystemComponentId | INTEGER | | AcSystem Component .SystemComponent Id | |
UserName | VARCHAR2(50) | | | |
EventTypeCode | INTEGER | | AcEventType .EventTypeCode | |
StartTimestamp | DATE | | | |
EndTimestamp | DATE | | | |
StatusCode | INTEGER | | AcStatus .StatusCode | |
ServiceTypeCode | INTEGER | EventId | AcServiceType .ServiceType Code | |
AcEventType
Contains the codes and descriptions for event types, including the following data:
Event type code, including the following predefined values:
1 through 7
Event type description, including the following predefined values:
Generate, Print, View, Delete, Admin., Query, Search
Table 30‑12 shows the structure of the AcEventType table.
Table 30‑12 Structure of the AcEventType table
Column | Data type/Values | Constraint | References | Key |
EventTypeCode | INTEGER1-7 | AcEvTy_EvTyCo_Idx | | Primary |
EventTypeDescription | VARCHAR2(50) | | | |
AcFileType
Contains the codes and descriptions for the following file type data:
File type codes, including the following predefined values:
1 through 39
File types, including the following predefined values:
UNKNOWN, DOX, DCD, HTM, HTML, ICD, IOB, PDF, ROL, ROP, ROS, ROV, ROW, RPTDESIGN, RPTDOCUMENT, RPTLIBRARY, RPTTEMPLATE, RTF, SMA, TXT, XLS
Table 30‑13 shows the structure of the AcFileType table.
Table 30‑13 Structure of the AcFileType table
Column | Data type/Value | Constraint | References | Key |
FileTypeCode | INTEGER1-39 | AcFiTy_FiTyCo_Idx | | Primary |
FileType | VARCHAR2(20) | | | |
AcJobType
Contains the codes and descriptions for the following job type data:
Job type codes, including the following predefined values:
1 through 3
Job type descriptions, including the following predefined values:
Async, Persistent, Transient
Table 30‑14 shows the structure of the AcJobType table.
Table 30‑14 Structure of the AcJobType table
Column | Data type/Value | Constraint | References | Key |
JobTypeCode | INTEGER1-3 | AcJoTy_JoTyCo_Idx | | Primary |
JobTypeDescription | VARCHAR2(20) | | | |
AcObjectOperation
Contains the codes and descriptions for the following object operation data:
Object operation codes, including the following predefined values:
1 through 6
Object operation descriptions, including the following predefined values:
Create, Delete, Modify, Login, Logout, Download
Table 30‑15 shows the structure of the AcObjectOperation table.
Table 30‑15 Structure of the AcObjectOperation table
Column | Data type/Value | Constraint | References | Key |
ObjectOperationCode | INTEGER | AcObOp_ObOpCo_Idx | | Primary |
ObjectOperation Description | VARCHAR2(20) | | | |
AcObjectType
Contains the codes and descriptions for the following object type data:
Object type codes, including the following predefined values:
1 through 6
Object type descriptions, including the following predefined values:
User, Role, Channel, Group, File, Folder
Table 30‑16 shows the structure of the AcObjectType table.
Table 30‑16 Structure of the AcObjectType table
Column | Data type/Values | Constraint | References | Key |
ObjectTypeCode | INTEGER | AcObTy_ObTyCo_Idx | | Primary |
ObjectTypeDescription | VARCHAR2(20) | | | |
AcOutputFormat
Contains the codes and descriptions for the following output format data:
Output format codes, including the following predefined values:
1 through 42
Output format descriptions, including the following predefined values:
UNKNOWN, PDF, XLS, ROW, DHTML, HTML, HTM, RTF, REPORTLET, XMLDISPLAY, XMLCOMPRESSEDDISPLAY, DHTMLRAW, DHTMLLONG, CSS, ANALYSIS, EXCELDISPLAY, EXCELDATA, EXCELDATADUMP, RTFFULLYEDITABLE, UNCSV, TSV, EXCEL, XMLDATADUMP, XMLREPORTLET, XMLCOMPRESSEDREPORTLET, XMLCOMPRESSEDEXCEL, XMLCOMPRESSEDPDF, XMLCOMPRESSEDRTF, XMLSTYLE, XMLDATA, RPTDOCUMENT, RPTLIBRARY, RPTTEMPLATE
Table 30‑17 shows the structure of the AcOutputFormat table.
Table 30‑17 Structure of the AcOutputFormat table
Column | Data type/Values | Constraint | References | Key |
OutputFormatCode | INTEGER1-42 | AcOuFo_OuFoCo_Idx | | Primary |
OutputFormat Description | VARCHAR2(30) | | | |
AcResourceGroup
Contains the codes and descriptions for the following resource group data:
Resource group ID, including the following predefined value:
0
Resource group name, including the following predefined value:
NULL
Table 30‑18 shows the structure of the AcResourceGroup table.
Table 30‑18 Structure of the AcResourceGroup table
Column | Data type/Values | Constraint | References | Key |
ResourceGroupId | INTEGER | AcReGr_ReGrId_Idx | | Primary |
ResourceGroupName | VARCHAR2(128) | | | |
AcServiceType
Contains the codes and descriptions for the following service type data:
Service type code, including the following predefined values:
1 through 5
Service type description, including the following predefined values:
Factory, View, Encyclopedia, Integration, Cache
Table 30‑19 shows the structure of the AcServiceType table.
Table 30‑19 Structure of the AcServiceType table
Column | Data type/Values | Constraint | References | Key |
ServiceTypeCode | INTEGER | AcSeTy_SeTyCo_Idx | | Primary |
ServiceTypeDescription | VARCHAR2(50) | | | |
AcStatus
Contains the codes and descriptions for the following status type data:
Status codes, including the following predefined values:
0 through 1
Status descriptions, including the following predefined values:
Failure, Success
Table 30‑20 Structure of the AcStatus type
Column | Data type/Values | Constraint | References | Key |
StatusCode | INTEGER | AcSt_StCo_Idx | | Primary |
StatusDescription | VARCHAR2(20) | | | |
AcSystemComponent
Contains the log records for system components, including the following data:
System component ID
Volume, system, and server names
Table 30‑21 shows the structure of the AcSystemComponent table.
Table 30‑21 Structure of the AcSystemComponent table
Column | Data type/Values | Constraint | References | Key |
SystemComponentId | INTEGER | AcSt_StCo_Idx | | Primary |
VolumeName | VARCHAR2(50) | | | |
SystemName | VARCHAR2(50) | | | |
ServerName | VARCHAR2(50) | | | |
AcUsageLogOffset
Contains the following usage log data:
File offsets
Volume names
Last update timestamp
Table 30‑22 shows the structure of the AcUsageLogOffset table.
Table 30‑22 Structure of the AcUsageLogOffset type
Column | Data type/Values | Constraint | References | Key |
FileIndex | NUMBER, | | | |
FileOffset | NUMBER | | | |
VolumeName | VARCHAR2(50) | NOT NULL | | Primary |
LastUpdateTime Stamp | NUMBER | | | |
The ActuateLog schema contains the following indexes listed in
Table 30‑23.
Table 30‑23 Indexes in the ActuateLog schema
Index | Table.Column(s) |
AcApEv_AdEvId_Idx | AcAdminEvent.EventId |
AcApEv_ApEvId_Idx | AcApplicationEvent.EventId |
AcApEv_ExNa_Idx | AcApplicationEvent.ExecutableName |
AcApEv_FiTyCo_Idx | AcApplicationEvent.FileTypeCode |
AcApEv_JoTyCo_Idx | AcApplicationEvent.JobTypeCode |
AcAdEv_ObNa_Idx | AcAdminEvent.ObjectName |
AcApEv_OuNa_Idx | AcApplicationEvent.OutputName |
AcAdEv_ObTyCo_ObOpCo_Idx | AcAdminEvent.ObjectTypeCode, ObjectOperationCode |
AcErEv_ErCo_Idx | AcErrorEvent.ErrorCode |
AcErEv_ErEvId_Idx | AcErrorEvent.ErrorEventId |
AcErEv_ErSe_Idx | AcErrorEvent.ErrorSeverity |
AcErEv_EvTi_Id | AcErrorEvent.EventTimestamp |
AcErEv_SyCoId_Idx | AcErrorEvent.SystemComponentId |
AcErEv_UsNa_Idx | AcErrorEvent.UserName |
AcEv_EvId_Idx | AcStatus.EventId |
AcEv_SyCoId_Idx | AcEvent.SystemComponentId |
AcEv_StCo_Idx | AcEvent.StatusCode |
AcEv_SyTyCo_Idx | AcEvent.ServiceTypeCode |
AcEv_EvTi_Idx | AcEvent.EventTimestamp |
AcEv_EvTyCo_Idx | AcEvent.EventTypeCode |
AcEv_UsNa_Idx | AcEvent.UserName |
AcEvTy_EvTyCo_Idx | AcEventType.EventTypeCode |
AcFiTy_FiTyCo_Idx | AcFileType.FileTypeCode |
AcJoTy_JoTyCo_Idx | AcJobType.JobTypeCode |
AcObOp_ObOpCo_Idx | AcObjectOperation.ObjectOperationCode |
AcObTy_ObTyCo_Idx | AcObjectType.ObjectTypeCode |
AcOuFo_OuFoCo_Idx | AcOutputFormat.OutputFormatCode |
AcReGr_ReGrId_Idx | AcResourceGroup.ResourceGroupId |
AcSeTy_SeTyCo_Idx | AcServiceType.ServiceTypeCode |
AcSt_StCo_Idx | AcStatus.StatusCode |
AcSyCo_SyCoId_Idx | AcSystemComponent.SystemComponentId |