Appendix C : Microservice trouble shooting

Error codes, log entries, and points of failure

SOAP Log File Location

We are logging all SOAP_LOG messages in the listener.log file located in /var/log/listener.log. This is the same log file the datastream logging is utilizing to record successful creations or failures of derivatives.

How To Interpret the Logs

Each derivative created will still generate its normal logs captured in each of the service’s functions laid out in the includes directory. Logging has also been added to the SOAP server portion and returns values based on the successful fetching of fedora objects, the creation of derivatives (doubled up to account for failures in the SOAP server or Taverna), and the completion of a specific function. The logs take the familiar form of the listener.log but are differentiated by the SOAP_LOG label. A typical log stream generated by a service:

$this->log->lwrite (description, SOAP_LOG, $pid, $dsid, NULL, label)

Error Explanations & Points of Failure

Below is a table which outlines the messages that you will be receiving upon running any one of these functions. All functions have the same basic log output at each critical stage so only a few will be explained here.

allOcr

-2 Fedora object unsuccessfully fetched - see listener.log

-3 Derivative not created successfully - see listener.log

0 Function successful

Any other value Function failed - see listener.log

ocr

-2 Fedora object unsuccessfully fetched - see listener.log

-3 Derivative not created successfully - see listener.log

0 Function successful

Any other value Function failed - see listener.log

An example function:

function JP2($pid, $dsid = "OBJ", $label = "Compressed jp2")

{

$result = -1;

$this->log->lwrite("Function JP2 starting...", 'SOAP_LOG', $pid, $dsid, NULL,'INFO');

try

{

$fedora_object = $this->fedora_connect->repository->getObject($pid);

$this->log->lwrite("Fedora object successfully fetched", 'SOAP_LOG', $pid, $dsid, NULL, 'INFO');

}

catch (Exception $ex)

{

$this->log->lwrite("Fedora object not fetched", 'SOAP_LOG', $pid, $dsid, NULL, 'ERROR');

return -2;

}

if ($image = new Image($fedora_object, $dsid, 'jp2', $this->log, null))

{

$this->log->lwrite("Image derivative created", 'SOAP_LOG', $pid, $dsid, NULL, 'INFO');

}

else

{

$this->log->lwrite("Derivative not created", 'SOAP_LOG', $pid, $dsid, NULL, 'ERROR');

$result = -3;

}

$funcresult = $image->JP2($dsid . '_JP2', $label);

if ($funcresult == 0) {

$this->log->lwrite("JP2 function successful", 'SOAP_LOG', $pid, $dsid, NULL, 'INFO');

$result = 0;

} else {

$this->log->lwrite("JP2 function failed", 'SOAP_LOG', $pid, $dsid, NULL, 'ERROR');

$result = $funcresult;

}

return $result;

}

To keep the formatting of the logs the same, we used the messaging/logging files provided ($this->log->lwrite (description, SOAP_LOG, $pid, $dsid, NULL, label)) which made it easier to track the flow of each individual function as they were called.

Special Cases

(See the Function Inputs section for more details on specific function troubleshooting).

We have tested these functions on a breadth of file extensions and types with various errors pertaining to each of the commands used in the services.

For any alternate conversions of file types or operations on files outside of the scope of the current commands, it would be best to create a new microservice function from scratch with the added functionality. Most commands need specific options to work on certain file types which can be found in the documentation of the command in question.