Troubleshooting zero.core

How do I enable logging and tracing ?

IBM WebSphere sMash uses standard java.util.logging logging specifications. By default, logging information for a started application is written to an application's {apphome}/logs directory. The logs are separated out into 2 files, error-0-0.log and trace-0-0.log. The error log contains all messages of Java level INFO and higher severity, while the tracing log contains all messages from teh Java logging system. The logs are automatically rotated as required.

Additional Tracing and Logging can be enabled in 2 ways.

1. Specify -d or -v and -l as arguments on the command line.
   If there is a problem running any of the zero commands specify the -d option on the command line.

   zero -v

   Enable all logging.

   zero -d

   Enable minimal logging.

   zero -l=log.txt

   Redirect the log/traces to a specified file rather than standard out.

2. Use the /config/logging/levels attribute to configure the logging levels in your zero.config. The value of this attribute is a map of logger names and logging level pairs. The top-level logger names will be the same as the module names (e.g. zero.core, zero.kernel). More specific logger names are based on the package names within the modules. The following example shows how to set the logging levels for zero.core.config and zero.core.context.

   /config/logging/levels = {
   	"zero.core.config" : "FINE",
   	"zero.core.context" : "FINEST"
   }
   

How can I verify incoming requests or outgoing responses?

IBM WebSphere sMash runtime can log all request and response traffic including headers and the payload body to help debug application code. This can be done as follows.

• Set the /config/requestLogging configuration attribute in the application's zero.config file to true.

  /config/requestLogging = true

  The WebSphere sMash runtime will write the request and response headers and, body, if any, to a log file named request-log-"timestamp" in the logs directory of the application. One log file will be written per request. Do not set this property to true in a production environment.

  The maximum amount of request and response data written to the file is configurable by changing the /config/requestLoggingLimit value to the maximum size of the log file. The default value of this configuration directive is 16384 bytes.

How do I debug bad JSON resulting in a JsonParserException ?

WebSphere sMash provides JSON utilities (zero.json.Json for encoding and decoding JSON data. A call to Json.decode() can fail with a JsonParserException that shows up in the error logs, that might look like the following if it is passed in bad JSON data.

CWPZC1001E: Request processing terminated for URI:  /parse_json; error during request:  zero.json.JsonParserException: line 1:15: expecting String, found '}'

The error above indicates that there was an exception while parsing JSON data and that the parser indicates that at character 15 of the stream, it found a a } indicating the end of an object, while it was expecting a JSON encoded string. In this case, it is probably due to an extra comma towards the end of the stream.

You may also see an error response in the firebug console which is a variation of the message in the error log

{"errorStatusCode":500,"rootCause":"antlr.MismatchedTokenException: expecting String, found '}'","errorMessage":"Error"}

It would be useful in these cases to examine the JSON data to determine where the error is. If the input data was part of the request payload (POST body), it can be examined by turning on request logging as described above. Alternatively, you can have the WebSphere sMash runtime trace part of the input data that caused this error by turning on the logging for zero.json. This can be done as follows in the application's zero.config file.

/config/logging/levels = {
	"zero.json" : "FINE"
}

You would see a log message in the trace log like the following that shows the bad JSON data with the trailing comma in this case

        zero.json.Json::decode Thread-11
        FINE [ Failed to decode input as JSON: {"name":"foo",} ]

What do I if "zero start" returns "Application already started" when the application is definitely not running?

In certain circumstances, it is possible for an application to get into a state where it believes it is started when it is not. This can occur if the the application is running when the computer is hard reset, or not shutdown correctly. For example, in the case of a power failure or removing the battery from a laptop, this situation can occur.

This occurs because of the recording of state information about the application which is normally cleaned up on orderly shutdown. The problem can be corrected by removing the files containing the state of the application before the hard reset occurred. Delete the following directory recursively:

After deleting this directory, it will be possible to start the application again. This action should only be taken on an application that can not be started after a reboot. Performing this action on a running application will leave the application in an indeterminate state.

What do I do when I see "At least one request did not return before the stop/recycle timeout" in the logs

This means that the application could not be cleanly quiesced during a recycle because one or more requests did not complete processing. This timeout can be adjusted by specifying the time in seconds for the configuration property /config/maxStopTime. This value defaults to 60 seconds.

To help with identifying the requests that do not complete, you can set the configuration property /config/createDumpOnErrantRequest to true to generate a java thread dump of the process.

The request dump files are created in the application's root directory.

Known Issues

UTF-8 JSON text file can not be parsed correctly