BI Publisher Logging & Debugging - Part 2

This is a follow up from the yesterday’s post. Now you know what type of logging options are available for you to debug and further analyze your BI Publisher reporting.

Today, I’d like to focus on the first debugging option, ‘Logging for Reports Generation’ and discuss how to enable your BI Publisher instance to start generating such logging information.

You can enable the logging feature by preparing a appropriate BI Publisher debug configuration file. This is a manual work and not be able to set from its administration UI. Once you have configured it requires the server to restart.

Configuration for Enabling Report Generation Log

Here is the steps to follow to enable the ‘Logging for Reports Generation’.

Steps to Enable Report Generation Debug:

1. Create a directory where you want the log files to be stored.
   e.g. D:\BI_Debug
   
2. Identify the JDK home, which is used by your J2EE Server, such as OC4J, on which BI Publisher Enterprise Server is running.

If you are not sure about where is your JDK home is, here is an example of how you can find the JDK home. When you have installed BI Publisher as part of BI EE suite and with embedded OC4J server then you can find the JDK home in the OC4J launch program. The launch program, oc4j.cmd, can be found at

<ORACLE_BI_HOME>\oc4j_bin\bin\oc4j.cmd

e.g. C:\OracleBI\oc4j_bi\bin\oc4j.cmd

When you open the file find ‘JAVA_HOME’ entry in the file, which shows the JDK_HOME location.

Example:

:::::::::: START CONFIGURATION SECTION :::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: set ORACLE_HOME=C:\OracleBI\oc4j_bi set JAVA_HOME=C:\Program Files\Java\jdk1.5.0_16 set J2EE_HOME=%ORACLE_HOME%\j2ee\home

Once you find the JDK home location, follow the next steps.

1. Move to <JDK_Home>\jre\lib
2. Create a text file called: xdodebug.cfg
3. Add the following 2 lines in this file:
   

   LogLevel=STATEMENT LogDir=<BI_Debug_Log_Directory>

   Example:

   LogLevel=STATEMENT LogDir=D:\BI_Debug

4. Save the file at the <JDK_Home>\jre\lib
5. Restart your J2EE Application Server such as OC4J server.
   This will enable the Java runtime that is used by BI Publisher Enterprise Server to identify the configuration file xdodebug.cfg

With the above configuration BI Publisher Enterprise Server will start generating ‘various files’ under the specified log folder. I’ll expain what are those ‘various files’ below.

BI Publisher Reports Generation Log File and More

Once you enabled the report generation ‘Debug’ mode as described above BI Publisher Server now starts generating the following output files under the folder that you have specified in the xdodebug.cfg file.

• xdo.log
• XML Data file
• Template file(RTF, etc)
• XSL file
• XSL-FO file
• Formatted FO file (with Data)
• Final Output file

Among all the above files the file you would mostly need and appreciate is ‘xdo.log’ file, which logs all the reports generation processing related information including a data generation and a report output generation. You can also find all the temporary files, which are generated during the report generation process such as XML data file, XSL file, and FO file, and the final output file under the same log folder. I’ll explain each of the files in the following sections.

What Can Each File Do for Me?

Main Log File - xdo.log

This is a main log file that logs all the reports generation processes related information. While various things you can find from this file there are a couple points that would be very valuable for you to review.

Fist, you can find SQL queries and parameter values that are used to retrieve data from a database. Second, you can find report layout generation related information, which tells you errors/exceptions with your RTF templates if any. Third, you can find a total time spent for each of the report generation processes, such as retrieving data from data source and generating a XML file, converting from RTF template to XSL-FO, merging XSL-FO with the XML data to generate FO and generating a final report output.

The below is a list of information you can find in the log file.

Data Generation Layer

• SQL Queries for Parameters
• SQL Queries for Report Data
• Parameter Name, Default Value
• Assigned values for Parameters

Report Layout Generation Layer

• Processing Information by RTF Processer: Converting from RTF template to XSL-FO style sheet
• Warning about RTF Template
  (e.g. “Old RTF version detected, nested table disabled”)
• Processing Information by FO Processer: Matching with the data and generating a final report output

Summary Section

• Total time for Data Generation
• Total time for converting RTF to XSL-FO
• Total time for merging XSL-FO with Data to generate FO
• Total time for generating a final output such as PDF, HTML, etc

 

XSL-FO(xdo_…rtf_out.xsl)

This is a XSL-FO style sheet, which is converted from a RTF template file by BI Publisher’s internal RTF processer. You can analyze this style sheet file to see how your RTF template is converted and how each item in the RTF template has been translated into XSL/XPATH/FO languages.

XML Data File(xdo_…fo_data.xml):

This is a XML data file that is generated by BI Publisher based on the sql queries used for the report. You can verify this file to see if the data is retrieved from databases and presented in the XML file as you expected. Also you can use this file to preview the report output with BI Publisher Template Builder (MS Word Add-in) for your report output review.

RTF Template(xdo_….rtf_template.rtf):

This is the RTF template file that is registered with this report and used for this report generation. It should be as same as the one you have uploaded and the one you can download from the report edit window in BI Publisher Enterprise Server UI. You can use this RTF template with a combination of the above XML data file to preview the report output using BI Publisher Template Builder (MS Word Add-in) for further analysis.

Output File (xdo_…out):

This is a final output file that is generated by BI Publisher. While the file extension is always ‘.out’ the file content format depends on the report output type that is chosen at the runtime.

For example if the output was selected as HTML then the output file format is HTML. You can change the file extension to be ‘.html’ and open in the browser to see the report output. If the output was selected as PDF, the output file contains PDF binary data and you can open the file after you change the file extension to be ‘.pdf’.

Conclusion

Now you have much better understanding behind the BI Publisher’s reporting process and great tools to analyze your report generation process and the performance.

I will discuss on how to enable the ‘BI Publisher Server Level System Log’ and how to use it tomorrow, so stay tuned!