Troubleshooting OFBiz
From TroubleshootingWiki
| Official Page |
| Project Documentation |
| Download |
|
Contents |
[edit] Debugging Techniques
Since the OFBiz framework is comprised of a number of different concepts and programming languages (Java, Minilang, FreeMarker, BeanShell) there is no single technique to debug the code. To gain visibility at run-time, a number of different techniques must be applied, ranging from the full debug capabilities of Eclipse or another IDE, to outputting messages and variable values to the logs or even the screen.
[edit] Logging
OFBiz writes to a number of different logs which are stored in the directory ${ofbizInstallFolder}\runtime\logs. The access_log files are similar to the access log files of the Apache HTTP Server and contain every request made to the server. These are handy to archive and can be used by programs such as AWStats (http://awstats.sourceforge.net) to produce graphical information on the site's traffic activity.
[edit] console.log
By default, OFBiz writes the contents of the console to this file. However, we may want to watch for an error in real time, and so choose to write the contents of the console to the console and watch the logs scroll up the window. This is achieved by editing the startofbiz.bat file and removing the > runtime\logs\console.log.
[edit] ofbiz.log
This is the main log in OFBiz and contains all logging messages generated by the framework. Once it is full, it is renamed ofbiz.log.1 and ofbiz.log starts from empty. Each log is full when it reaches 1000KB (roughly 1MB) and a total number of 10 backup files are stored. Writing to a small log file is more efficient than writing to a large one so it is better to keep the log file down to a reasonable size for performance issues. Depending on the site traffic 10MB of logs may be sufficient, although this is configurable.
[edit] Configuring the Logs
How much information these logs display is configurable and the level of information displayed is controlled in the file debug.properties, in the directory framework\base\config.
By default, the only level that is switched off is print.verbose. Notice that the value is ftrue. It doesn't have to be set to false to be false. It can be any value but true. Try switching this to true and restarting. Verbose logging displays an enormous amount of information, stretching all the way back to entity engine activities, showing queries and prepared statements, database pooling, and transactional information. The more information that is written to the logs, the longer it takes to create these logs, and having the debugging levels set to display too much information will have serious performance consequences. It is recommended that for production environments everything below warning is switched off. This means that only fatal errors, errors, and warnings are displayed.
To change the size of the ofbiz.log files and the number of historical backup files that are stored change the values of the following properties:
log4j.appender.file.MaxFileSize=1000KB log4j.appender.file.MaxBackupIndex=10
A considerable amount of work has been undertaken on the logging since OFBiz 4.0 was released. In the next release of OFBiz we can look forward to a greater visibility, with the ability to write log levels into their own files rather than all lumped into one large file.
[edit] Viewing the Logs through Webtools
The log4j appender css writes logs in an XHTML format to a file ofbiz.html. This file is accessible through the Webtools console and is displayed to us neatly formatted. This useful feature eliminates developers needing server root access just to gain access to the logs.
To find the logs, open up the Webtools console (https://localhost:8443/webtools/control/main) and select View Log.
The logging level can also be changed just for one session through the Webtools console by selecting Adjust Debugging Levels.
[edit] Writing Information to the Logs
In Java code we have already briefly met the handy OFBiz utility class Debug. We can make use of this to write the information we wish to log at any particular level. For example:
Debug.logVerbose("This is a Verbose Logging Message", module);
The module parameter passed in is a static class variable with a value of the name of the class. This gives the logger the information it needs to tell us where the log message came from. For example:
public static String module = LearningEvents.class.getName();
The following methods are the most commonly used:
Debug.logVerbose("Message", module);
Debug.logInfo("Message", module);
Debug.logImportant("Message", module);
Debug.logWarning("Message", module);
Debug.logError("Message", module);
Debug.logFatal("Message", module);
We may wish to determine a course of action and perform a lookup or an extra function depending on whether a particular logging level is on. For example, we may wish to display (in the logs) a person's name instead of just their partyId, but only when verbose logging is on. Let's say that this person's name is not to hand and requires another lookup. We can perform a very quick check using the Debug.verboseOn() method to determine if this logging level is on. So:
if(Debug.verboseOn()){
try{
GenericValue person = delegator.findByPrimaryKey ("Person", UtilMisc.toMap("partyId", partyId));
Debug.logVerbose("This is person : " + person.getString("firstName") + " " + person.getString("lastName"), module);
}
catch(GenericEntityException e){
// Handle this error
}
}
[edit] Logging Minilang
Logging is the only way to currently debug through Minilang and again can be restricted by level:
<log level="info" message="This is the Debug Message - ${someField}"/>
The levels are verbose, info, important, warning, and error. Since often these log messages are temporary and used to check the value of a variable while debugging the simple methods, it is handy to place an immediately recognizable String at the start of the message to make the message stand out in the logs. For example, place the following log message inside the removePlanetReview simple-method in LearningServices.xml:
<log level="info" message="Removing planetId = ${parameters.reviewId}"/>
Then fire an http request ListPlanetReviews to our learning webapp and remove a review.
If we have the console log logging to the console and not the file we should see:
Notice that our log message is nestled amongst other messages and we had to scroll back in the logs to find it. Now change the log message to:
<log level="info" message="************ Removing planetId = ${parameters.reviewId}"/>
Remove another review and take a look in the logs:
The asterisks make our log message stand out much clearer to the naked eye. Obviously, if we had been printing out to the console.log, we could have searched the log file for planetId and been taken directly to the correct message.
[edit] Debugging Java Code
Eclipse can connect to a remote Virtual Machine (VM) running a Java application and connect it to the internal debugger. Once successfully connected debugging is almost as if we were debugging a local application that is running within the IDE. We can inspect variables, set breakpoints, and step through code, giving us complete visibility as to what is happening with our code at runtime.
The advantage of this is that we can connect and debug through code (providing that the code being executed remotely is identical to our local code) in OFBiz without having to spend time getting it running inside our IDE and can debug the application out of the box. Should we need to, we could connect to another developer's application or even our test staging platform's application and debug. Though this is the OFBiz recommended way for debugging java code, there is also a more traditional solution. You can see how to use it, look for Debugging (or running) OFBiz in Eclipse at http://docs.ofbiz.org/x/gQ. We do not have to do anything special to OFBiz to get this to work. We just have to make sure that the correct parameters are passed in to the VM at runtime. These parameters have already been added for us, but commented out. All we need to do is make sure that we start OFBiz using the correct command.
[edit] Passing in the VM Parameters
Open startofbiz.bat and place REM before the first line:
"%JAVA_HOME%\bin\java" -Xms256M -Xmx512M -Duser.language=en -jar ofbiz.jar > runtime\logs\console.log
And delete REM from the last line:
"%JAVA_HOME%\bin\java" -Xms256M -Xmx512M -Duser. language=en -Xdebug -Xnoagent -Djava.compiler=NONE - Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 -jar ofbiz.jar > runtime\logs\console.log
The next time OFBiz is started the VM is configured to use the Java Platform Debugger Architecture (JPDA) and we can connect to our application and debug using port 5005. In the unlikely event that port 5005 is in use by something, simply change this port to a free one.
It is important that the VM is not configured to use the JPDA in production. If anyone connects their debugger to this port they can cause the application to hang just by placing a breakpoint in a commonly called piece of code.
[edit] Configuring the Remote Debugger
With OFBiz started, open our Eclipse project and click on the down arrow just to the right of the bug icon and select Open Debug Dialog:
The Debug dialog will open. In the left-hand panel double-click on Remote Java Application and in the Name field type OFBiz4.0, in the Project field Browse for our ofbiz 4.0 project and in the Port field type 5005, then click Apply to save these details.
After the settings are saved, click Debug to connect the debugger. In the future to connect the debugger select the arrow to the right of the bug icon and choose OFBiz4.0.
Open up the class org.ofbiz.learning.learning.LearningServices, find the method createPlanetReview and in the left-hand margin of the first line containing code, right-click and select Toggle Breakpoint:
When this line of code is executed, the application will pause at this breakpoint and wait for a command like continue or step to the next line. Your local copy of the code must be identical to the compiled code that is being executed or some strange results will be noticed. Pausing on or stepping to an empty line are the most common strange effects.
Fire an http request PlanetReview to our webapp learning and create any review. The application appears to hang, the browser page shouldn't have changed and Eclipse should be flashing Orange in the task bar:
If we return to Eclipse we are now in the Debug perspective, and we can see that the thread is suspended in the Debug window in the top-left corner.
We can now step through our code, inspecting variables and using Eclipse's full range of debugging tools. Click on the top level Run menu to see a full list of possibilities.
We should also notice that the line we set the breakpoint on is now highlighted:
Hit F6 to step over this line to the next line. Now double-click on the planetId variable to highlight it, right-click and select Inspect to see information on the value of this variable:
Once finished select the Disconnect button from the panel to disconnect the debugger:
Finally select the Java perspective in the very top-right-hand corner to return to our original perspective:
[edit] Additional References
For instructions on advanced techniques for Installing OFBiz, click here
[edit] Source
The source of this content is Chapter 14: Troubleshooting OFBiz of Apache OFBiz Development: The Beginner's Tutorial by Rupert Howell, Jonathon Wong (Packt Publishing, 2009).
