<div id="api_guide">
  <h2>Logging</h2>

  <p>The application logs at four different levels DEBUG, INFO, WARNING and ERROR. In general the log messages
  likely to be the most interesting are the ERROR messages - and in fact in a live application you will
  never see the DEBUG level messages. An error message will only ever be written to the log if the generation of
  the exchanges was halted in any way. The error message is normally passed back to the caller of the service
  as described in the error sections of the
  <%= link_to("Output Formats", {:controller => :api, :action => :output_format}) %> documentation.</p>

  <p>The log file is normally found at the root of the application server and is called <code>kidney_log.txt</code>.
   This log file will grow in size over the years, if it becomes large enough that you want to remove it, it can
   simply be deleted. The file while then be recreated on when the algorithms are next run.</p>

  <div id="logging_levels">
    <h3>Logging Levels</h3>
    <dl>
      <dt><strong>DEBUG</strong></dt>
      <dd>debug messages are not written to the file as standard and will only really be useful to system developers.</dd>

      <dt><strong>INFO</strong></dt>
      <dd>info messages tend to give out progress and intermediate information, and also what operation is
      currently taking place. This is obviously useful when finding out where something went wrong.</dd>

      <dt><strong>WARN</strong></dt>
      <dd>warning messages are non-fatal errors. They tend to be used for problems that may indicate something is wrong but
      are not full blown failures.</dd>

      <dt><strong>ERROR</strong></dt>
      <dd>error messages are critical errors that have stopped the algorithm from continuing or producing a result.
      They generally indicate a major problem with the system, for example unexpected data formats, invalid/unknown
      parameters passed, unexpected system state, etc.</dd>
    </dl>
  </div>

  <div id="logging_format">
    <h3>Example Log Files</h3>
    <p>Below is an example of what the log file <em>might</em> look like during a successful run of the algorithms.</p>
    <pre class="logging_example" id="successful_example">
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:93]	Setting Pairwise Algorithm....
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:99]	Checking for altruistic donors....
     - Tue Dec 14 14:18:51 2010 : INFO : [ExchangeList.cpp:122]	Building data structures....
     - Tue Dec 14 14:18:51 2010 : INFO : [ExchangeList.cpp:144]	Finished building data structures....
     - Tue Dec 14 14:18:51 2010 : INFO : [ExchangeList.cpp:122]	Building data structures....
     - Tue Dec 14 14:18:51 2010 : INFO : [ExchangeList.cpp:144]	Finished building data structures....
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:106]	Finding cycles....
     - Tue Dec 14 14:18:51 2010 : INFO : [CycleCalculator.cpp:34]	Calculating two-cycles....
     - Tue Dec 14 14:18:51 2010 : INFO : [CycleCalculator.cpp:56]	Found 5 2-cycles
     - Tue Dec 14 14:18:51 2010 : INFO : [CycleCalculator.cpp:67]	Calculating three-cycles....
     - Tue Dec 14 14:18:51 2010 : INFO : [CycleCalculator.cpp:93]	Found 9 3-cycles
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:114]	Removing any altruistic cycles as required....
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:121]	Finding solution strategy....
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:129]	Running algorithm
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:131]	Finished running algorithm (LEMON) Altruistic Pairwise Exchanges
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:129]	Running algorithm
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:131]	Finished running algorithm (COIN) Optimal backarcs strategy at iteration 1
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:129]	Running algorithm
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:131]	Finished running algorithm (COIN) Optimal backarcs strategy at iteration 2
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:129]	Running algorithm
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:131]	Finished running algorithm (COIN) Optimal backarcs strategy at iteration 3
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:129]	Running algorithm
     - Tue Dec 14 14:18:51 2010 : INFO : [IPAlgorithm.cpp:131]	Finished running algorithm (COIN) Optimal set of exchanges with backarcs
    </pre>

    <p>The log file takes the format:</p>
    
    <pre class="logging_example">
      - DATE : LEVEL : [SOURCE CODE FILE AND LINE NUMBER] MESSAGE
    </pre>

    <p>
      The info messages in the log example above give an indication of the algorithm's progress and the strategy
      being used by the algorithm. Also output are the total number of two-way and three-way cycles found as the algorithm
      is progressing.      
    </p>

    <p>Below we present an example of a log file containing an error message. These messages will almost certainly be
    unrecoverable failures, and it the case below the parsing has failed as a result of an expected element "data" not
    being present in the JSON input data passed to the service.</p>

    <pre class="logging_example">
      - Tue Dec 14 11:39:22 2010 : INFO : [Parser.cpp:41]	Starting to parse file....
      - Tue Dec 14 11:39:22 2010 : ERROR : [JsonParser.cpp:38]	No data element found in the JSON passed
    </pre>
  </div>
</div>