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 31‑7 shows the structure of the AcAdminEvent table.
Table 31‑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 31‑8 shows the structure of the AcApplicationEvent table.
Table 31‑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 31‑9 shows the structure of the AcErrorEvent table.
Table 31‑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 31‑10 shows the structure of the AcErrorLogOffset table.
Table 31‑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 31‑11 shows the structure of the AcEvent table.
Table 31‑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 31‑12 shows the structure of the AcEventType table.
Table 31‑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 31‑13 shows the structure of the AcFileType table.
Table 31‑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 31‑14 shows the structure of the AcJobType table.
Table 31‑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 31‑15 shows the structure of the AcObjectOperation table.
Table 31‑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 31‑16 shows the structure of the AcObjectType table.
Table 31‑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 31‑17 shows the structure of the AcOutputFormat table.
Table 31‑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 31‑18 shows the structure of the AcResourceGroup table.
Table 31‑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 31‑19 shows the structure of the AcServiceType table.
Table 31‑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 31‑20 shows the structure of the AcStatus table.
Table 31‑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 31‑21 shows the structure of the AcSystemComponent table.
Table 31‑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 31‑22 shows the structure of the AcUsageLogOffset table.
Table 31‑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 31‑23.
Table 31‑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