Using the Log Analysis Utility to Identify Problems

About the Log Analysis Utility

The Log Analysis Utility is a command-line utility that helps you quickly identify the cause of issues reported by Oracle Enterprise Performance Management System components by analyzing the applicable log files. Because this utility automates log file analysis, you do not need to manually locate and scan EPM System log files to identify issues. Information required to troubleshoot the issue or to escalate it to Oracle Support is quickly available by running this utility. Run on the server where Oracle Hyperion Foundation Services is installed, this utility accesses and analyzes log files on all the servers identified in the Oracle Hyperion Shared Services Registry of an EPM System instance.

Using the Log Analysis Utility, you can:

List EPM System errors that occurred within a time period. System issues are related to services, intercomponent communication errors, and user directory communication errors.
List functional issues that occurred within a time period. Functional issues are related to EPM System component functionalities; for example, failure during an Oracle Essbase calculation run or the forms load process in Oracle Hyperion Planning or Oracle Hyperion Financial Management.
Trace an Execution Context ID (ECID) through log files to trace user sessions across EPM System components. ECID is a unique identifier that is used to correlate events that are part of the same request execution flow. ECID is an Oracle standard unique ID.

Prerequisites

Any user who has access to EPM_ORACLE_INSTANCE/bin; for example, C:/Oracle/Middleware/user_projects/epmsystem1/bin on a Windows server, can run the Log Analysis Utility.

Users running the Log Analysis Utility must have execute privileges on the following files:

Windows: EPM_ORACLE_INSTANCE/bin/loganalysis.bat
Users running the Log Analysis Utility must have read permission on the files and directories within MIDDLEWARE_HOME/user_projects on all server machines that host EPM System components. Users must also have write permission on the directory where the utility creates its reports.

If log files are not stored in a location within MIDDLEWARE_HOME/user_projects, users running the utility must have read permission on the log files in their custom location.

Location of Log Analysis Utility Reports

Log Analysis Utility creates an HTML report based on the command options that you specify and stores it in EPM_ORACLE_INSTANCE/diagnostics/reports, for example, in C:/Oracle/Middleware/user_projects/epmsystem1/diagnostics/reports on a Windows server.

Generally, the Log Analysis Utility uses the following report-naming convention:

LogAnalysis_Report_YYYY_MM_DD_HR_MIN_SEC.html

Log Analysis Utility provides a command option that enables you to specify a unique report name.

Note:

If the contents of Log Analysis Utility reports are garbled, remove the -Dfile.encoding=UTF-8 directive from the Log Analysis Utility executable (EPM_ORACLE_INSTANCE/bin/loganalysis.bat or EPM_ORACLE_INSTANCE/bin/loganalysis.sh), and then regenerate the report.

Log Analysis Utility Options

The options for using the Log Analysis Utility:

loganalysis [-all | -system | -functional | -m [ERROR | INCIDENT_ERROR
WARNING | NOTIFICATION | TRACE]] [-t [<TIME FROM> <TIME TO>] -tday <days> -thour <hours> -tmin <minutes>] -ecid <ecid> -s <SEARCH STRING> -d <Offline log files directory> -f <file with message ids to filter from the report> -maxsize <max report size in MB>

Table 3-1 Log Analysis Utility Parameters

Parameter	Description
`-h`	Displays the help page. Example: `loganalysis -h`
`-system`	Generates a report containing `ERROR` and `INCIDENT_ERROR` log message types. Typically used by EPM System IT Administrators. Example: `loganalysis -system`
`-functional`	Generates a detailed report that contains messages that are of type `WARNING`, `NOTIFICATION`, and `TRACE`. Typically used by EPM System Functional Administrators. Example: `loganalysis -functional`
`-ecid <ECID>`	Generates a report that traces an activity that was performed across EPM System components. Takes an ECID as the argument. This report is used to trace an error across EPM System components. Generally, this option is used after you identify an error by running a report using the `-all`, `-system`, or `-functional` option, and want to trace the activity that led to the error. See Finding the ECID of a User Activity. Note: ECID that contains the caret symbol (^) must be enclosed in quotation marks. Example: `loganalysis -ecid "0000Jet8kA6ESOG_Ix5Eif1G^RAF000005"`
`-m <ERROR TYPE>`	Generates a report containing messages of a specified type. Takes one of the following error message types as the argument: `ERROR` `INCIDENT_ERROR` `WARNING` `NOTIFICATION` `TRACE` Example: `loganalysis -m ERROR`
`-o <TITLE>`	Generates a report with a custom report title. Takes a report title, enclosed in double quotation marks, as the argument. Example: `loganalysis -m ERROR -o "myError Report"` creates a report titled `myError Report.html`, which contains log messages of type `ERROR` contained in all log files. Be sure to use quotation marks to enclose the report name.
`-s <STRING>`	Generates a report on log messages that contain the specified string. Takes an error string, enclosed in double quotation marks, as the argument. Example: `loganalysis -system -s "Failed to connect to DB" -o "DB Connection Errors"` creates a report with the title `DB Connection Errors.html`, which lists all messages of type `ERROR` and `INCIDENT_ERROR` that contain the string `Failed to connect to DB`.
`-t <FROM DATE>`T`<FROM TIME><TO DATE>`T`<TO TIME>`	Generates a report on log messages that were generated within the specified time period. Takes a space-separated "from" time and a "to" time as the argument. "From" time and "to" time must be specified in `YYYY-MM-DDTHOUR:MIN:SEC` format using a 24-hour clock. Example: `loganalysis -all -t 2012-08-10T12:00:00 2012-08-10T23:59:59 -o "All Messages on August_10_2012"` creates `All Messages on August_10_2012.html`, which contains all log messages generated between midnight and 11:59:59 p.m. on 08/10/2012.
`-tday <DAYS>`	Generates a report on log messages generated within the specified number of days. Takes a numeric value as the argument. Example: `loganalysis -ERROR -tday 3 -o "Error Messages for the last three days"` creates `Error Messages for the last three days.html`, which contains messages of type `ERROR` that were generated within the last three days.
`-thour <HOURS>`	Generates a report on log messages that were generated within the specified number of hours. Takes a numeric value as the argument. Example: `loganalysis -ERROR -thour 6 -o "Error Messages for the last six hours"` creates `Error Messages for the last six hours.html`, which contains messages of type `ERROR` that were generated within the last six hours.
`-tmin <MINUTES>`	Generates a report on log messages that were generated within the specified number of minutes. Takes a numeric value as the argument. Example: `loganalysis -ERROR -tmin 45 -o "Error Messages for the last 45 minutes"` creates `Error Messages for the last 45 minutes.html`, which contains messages of type `ERROR` that were generated within the last 45 minutes.
`-d <DIRECTORY PATHS>`	Generates a report on log files stored in specified directory paths. You use this option to analyze log files that are not stored in the default log file location of EPM System components. You can specify multiple log locations by using a comma-separated list of locations. Directory paths must be enclosed in double quotation marks. Example: `loganalysis -m INCIDENT_ERROR -d "c:/logfiles"`, `"z:/OracleLogs"`, `"y:/EPMLogs" "/net/epm_server2/Oracle/Middleware/user_projects" -o "myCustom Analysis Report"` creates a report titled `myCustom Analysis Report` listing messages of type `INCIDENT_ERROR` contained in the log files available in the specified directories.
`-f <arg>`	Not used in this release; reserved for future use.
`-maxsize <arg>`	Increases the report size. Default report size is 5 MB. Example: `loganalysis -all -o "Custom Analysis Report" -maxsize 15` generates a report that can be up to 15 MB in size. The report is titled `Custom Analysis Report` and contains all messages of in all log files.
`-all`	Generates a report listing messages in all log files. Generating this report may take awhile and may yield a large report file. Oracle does not recommend using this command option without other parameters that restrict the report scope. Example: `loganalysis -all`

Running the Log Analysis Utility

The Log Analysis Utility is a command line utility.

To run the Log Analysis Utility:

Start a command prompt on the server machine that hosts Foundation Services.
Navigate to EPM_ORACLE_INSTANCE/bin; typically, C:/Oracle/Middleware/user_projects/epmsystem1/bin on a Windows server.
Execute a command. Specify the appropriate command options for generating the report. See Table 3-1.

loganalysis.bat OPTIONS (Windows)

For example, use a command such as the following on a Windows server to create a report titled "Database Issues_1-21-2013_11AM", which contains messages related to an error that caused an EPM System component to lose database connectivity around 11 a.m. on November 21, 2012:

loganalysis -system -t 2013-01-21T11:15:00 2013-01-21T11:20:00 -s "Failed to connect to DB" -o "Database Issues_1-21-2013_11 AM".

Finding the ECID of a User Activity

ECID is a unique system generated identifier that correlates a user's activity across several EPM System components.

To find the ECID of a user's activity, you must first generate a Log Analysis Utility report. ECID, which is included in log message details, resembles the following:

0000Jet8kA6ESOG_Ix5Eif1G^RAF000005

To locate the ECID of a user activity:

Run the Log Analysis Utility and generate a report that lists system or functional errors. See Running the Log Analysis Utility.
From EPM_ORACLE_INSTANCE/diagnostics/reports (for example, C:/Oracle/Middleware/user_projects/epmsystem1/diagnostics/reports on a Windows server), open the report that you generated.