Zwischenspeicherung: Logging hinzugefügt.

git-svn-id: https://joinup.ec.europa.eu/svn/moa-idspss/trunk@313 d688527b-c9ab-4aba-bd8d-4036d912da1d

1 files changed, 88 insertions, 5 deletions

diff --git a/spss.handbook/handbook/install/install.html b/spss.handbook/handbook/install/install.html
index b380cdd40..2c68eacb0 100644
--- a/spss.handbook/handbook/install/install.html
+++ b/spss.handbook/handbook/install/install.html
@@ -45,8 +45,14 @@
                         <li><a href="#webservice_basisinstallation_installation_tomcatstartstop_verify">Pr&uuml;fen des erfolgreichen Starts</a> </li>
                       </ol>
                     </li>
-                    <li><a href="#webservice_basisinstallation_installation_changeonthefly">&Auml;nderung der Konfiguration im laufenden Betrieb</a>  </li>
-</ol>
+                    <li><a href="#webservice_basisinstallation_installation_changeonthefly">&Auml;nderung der Konfiguration im laufenden Betrieb</a></li>
+              </ol>
+            </li>
+            <li><a href="#webservice_basisinstallation_logging">Logging</a>
+              <ol>
+                <li><a href="#webservice_basisinstallation_logging_format">Format der Log-Meldungen</a></li>
+                <li><a href="#webservice_basisinstallation_logging_messages">Wichtige Log-Meldungen</a>   </li>
+              </ol>
             </li>
             </ol>
         </li>
@@ -173,7 +179,84 @@ In diesem Fall geben die <code>WARN</code> bzw. <code>ERROR</code> Log-Meldungen
 <p> Sie k&ouml;nnen die Konfiguration f&uuml;r MOA SP/SS im laufenden Betrieb aktualisieren, in dem Sie mittels eines Web-Browsers folgende URL aufrufen:</p>
 <pre> http://&lt;host&gt;:&lt;port&gt;/moa-spss/ConfigurationUpdate </pre>
 <p>Damit dies funktioniert, muss in der Konfiguration von Tomcat ein spezieller Benutzer sowie eine spezielle Benutzerrolle eingerichtet werden (vergleiche Abschnitt <a href="#webservice_basisinstallation_installation_tomcatconfig_moaadmin">2.1.2.2.3</a>). </p>
-<h2><a name="webservice_erweiterungsmöglichkeiten" id="webservice_erweiterungsmöglichkeiten"></a>2.2 Erweiterungsm&ouml;glichkeiten</h2>
+<h3><a name="webservice_basisinstallation_logging" id="webservice_basisinstallation_logging"></a>2.1.3 Logging </h3>
+<p>Das MOA SP/SS Webservice verwendet <a href="#referenziertesoftware">Jakarta Log4j</a> f&uuml;r die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsm&ouml;glichkeiten, die ausf&uuml;hrlich im  <a href="#referenziertesoftware">Jakarta Log4j</a> Handbuch  beschrieben sind. Unter anderem gibt es die M&ouml;glichkeit, folgende Einstellungen vorzunehmen:
+  <ul>
+      <li id="klein">
+        <p>Das verwendete Log-Level (<code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, <code>FATAL</code>);</p>
+      </li>
+      <li id="klein">
+        <p>Name und maximale Gr&ouml;&szlig;e der Log-Datei(en);</p>
+      </li>
+      <li id="klein">
+        <p>Das Aussehen der Log-Eintr&auml;ge.</p>
+      </li>
+  </ul>
+    <p>Das MOA SP/SS Webservice verwendet folgende Log-Hierarchien: </p>
+<ul>
+    <li>
+      <p><code>moa.spss.server</code> f&uuml;r alle Log-Meldungen aus dem MOA/SPSS Webservice; </p>
+    </li>
+    <li>
+      <p><code>iaik.server</code> f&uuml;r alle Log-Meldungen aus den IAIK Kryptographie-Modulen. </p>
+    </li>
+  </ul>
+    <p>Eine f&uuml;r MOA SP/SS passende Konfigurationsdatei f&uuml;r Log4j finden Sie <a href="../../conf/moa-spss/log4j.properties">hier</a>. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Datei <code>moa-spss.log</code> geschrieben. </p>
+  <h4><a name="webservice_basisinstallation_logging_format" id="webservice_basisinstallation_logging_format"></a>2.1.3.1 Format der Log-Meldungen</h4>
+      <p> Anhand einer konkreten Log-Meldung wird das Format der MOA SP/SS Log-Meldungen erl&auml;utert: </p>
+      <pre>INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=node1 
+  MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification
+</pre>
+<p>    Der Wert <code>INFO</code> besagt, dass die Log-Meldung im Log-Level <code>INFO</code> entstanden ist. Folgende Log-Levels existieren:</p>
+    <ul>
+      <li>
+        <p><code>DEBUG</code>: Log-Meldungen im Log-Level <code>DEBUG</code> geben Auskunft &uuml;ber die innere Arbeitsweise des Systems. Sie sind haupts&auml;chlich f&uuml;r Entwickler interessant.</p>
+      </li>
+      <li>
+        <p><code>INFO</code>: Diese Log-Meldungen geben Status-Informationen &uuml;ber den Ablauf des Webservices, wie z.B. &uuml;ber das Einlangen einer neuen Anfrage.</p>
+      </li>
+      <li>
+        <p><code>WARN</code>: Bei der Ausf&uuml;hrung einer Anfrage sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeintr&auml;chtigt.</p>
+      </li>
+      <li>
+        <p><code>ERROR</code>: Die Ausf&uuml;hrung einer Anfrage musste abgebrochen werden. Das Webservice ist davon nicht beeintr&auml;chtigt. </p>
+      </li>
+      <li>
+        <p><code>FATAL</code>: Es ist ein Fehler aufgetreten, der den weiteren Betrieb des Webservices nicht mehr erlaubt.</p>
+      </li>
+    </ul>
+    <p>Der n&auml;chste Wert <code>01 21:25:26,540</code> gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 1. Tag im aktuellen Monat, sowie die genaue Uhrzeit). </p>
+    <p>      Der Wert <code>Thread-3</code> bezeichnet den Thread, von dem die Anfrage bearbeitet wird.</p>
+    <p>      Der Wert von <code>TID</code> gibt die f&uuml;r jede Anfrage eindeutige Transaktions-ID an. Log-Meldungen, die bei der Abarbeitung dieser Anfrage geschrieben werden, enthalten alle einen Hinweis auf die entsprechende Transaktions-ID.</p>
+    <p>      Der Wert von <code>NID</code> gibt den Rechner-Knoten an, auf dem das MOA SP/SS Webservice l&auml;uft (bei <code>NID=&lt;null&gt;</code> ist dieser Wert nicht konfiguriert, vergleiche Abschnitt <a href="#webservice_basisinstallation_installation_spssdeploy">2.1.2.3</a>).</p>
+    <p>      Der Rest der Zeile einer Log-Meldung ist der eigentliche Text, mit dem das System bestimmte Informationen anzeigt. Im Fehlerfall ist h&auml;ufig ein Java Stack-Trace angef&uuml;gt, der eine genauere Ursachen-Forschung erm&ouml;glicht.</p>
+    <h4>      <a name="webservice_basisinstallation_logging_messages" id="webservice_basisinstallation_logging_messages"></a>2.1.3.2 Wichtige Log-Meldungen</h4>
+    <p>      Neben den im Abschnitt <a href="#webservice_basisinstallation_installation_tomcatstartstop_verify">2.1.2.4.3</a> beschriebenen Log-Meldungen, die anzeigen, ob das Service ordnungsgem&auml;&szlig; gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss &uuml;ber die Abarbeitung von Anfragen. </p>
+    <p>Die Entgegennahme einer Anfrage wird angezeigt durch:
+      
+  </p>
+    <pre>INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=&lt;null&gt; 
+  MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification
+INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=&lt;null&gt; 
+  MSG=Aufruf von Adresse=127.0.0.1
+INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=&lt;null&gt; 
+  MSG=Client-Zertifikat nicht verf&uuml;gbar</pre>
+    <p> Die dritte Log-Meldung besagt, dass f&uuml;r die Abarbeitung dieser Anfrage kein Client-Zertifikat verf&uuml;gbar ist (entweder, weil die Anfrage &uuml;ber HTTP eingelangt ist, oder weil die SSL Client-Authentisierung nicht eingeschaltet ist). Bei erfolgreicher SSL Client-Authentisierung, gibt beispielsweise folgende Log-Meldung Informationen &uuml;ber das Client-Zertifikat aus: </div>
+  <pre>INFO | 12 13:58:08,772 | Thread-10 | TID=1045054687159-2 NID=&lt;null&gt; 
+  MSG=Client-Zertifikat: Subject=CN=Testuser, OU=MOA, O=BRZ, L=Vienna, ST=Vienna, C=AT, 
+  Serial=1.039.104.204, Issuer=CN=TestCA, OU=MOA, O=BRZ, L=Vienna, ST=Vienna, C=AT</pre>
+  <p>Eine erfolgreich abgearbeitete Anfrage wird angezeigt durch:
+  </p>
+  <pre>INFO | 01 21:25:53,168 | Thread-3 | TID=1049225059594-106 NID=&lt;null&gt; 
+  MSG=Anfrage erfolgreich abgearbeitet</pre>
+  <p>Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch:  </p>
+  <pre>INFO | 01 21:25:27,642 | Thread-3 | TID=1049225059594-100 NID=&lt;null&gt; 
+  MSG=Fehler beim Abarbeiten der Anfrage</pre>
+  <div id="block">
+    <p>In diesem Fall gibt der mitgeloggte Stacktrace Auskunft &uuml;ber die Art des Fehlers. Der Aufrufer des MOA SP/SS Webservices bekommt einen Fehlercode sowie eine kurze Beschreibung des Fehlers als Antwort zur&uuml;ck. </p>
+    <p> Die Tats&auml;chlich &uuml;bertragenen Anfragen bzw. Antworten werden aus Effizienzgr&uuml;nden nur im Log-Level <code>DEBUG</code> angezeigt. </p>
+  </div>
+  <h2><a name="webservice_erweiterungsmöglichkeiten" id="webservice_erweiterungsmöglichkeiten"></a>2.2 Erweiterungsm&ouml;glichkeiten</h2>
 <p>Ausgehend von der <a href="#webservice_basisinstallation">Basisinstallation</a> k&ouml;nnen die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabh&auml;ngig und in beliebiger Kombination aufgesetzt werden.</p>
   <h3><a name="webservice_erweiterungsmöglichkeiten_webserver" id="webservice_erweiterungsmöglichkeiten_webserver"></a>2.2.1 Vorgeschalteter Webserver</h3>
   <h4><a name="webservice_erweiterungsmöglichkeiten_webserver_apache" id="webservice_erweiterungsmöglichkeiten_webserver_apache"></a>2.2.1.1 Apache</h4>
@@ -222,8 +305,8 @@ In diesem Fall geben die <code>WARN</code> bzw. <code>ERROR</code> Log-Meldungen
     <td>Java 2 Standard Edition in der Version 5.0 (Software Development Kit bzw. Java Runtime Environment) </td>
     </tr>
   <tr>
-    <td>&nbsp;</td>
-    <td>&nbsp;</td>
+    <td><a href="http://jakarta.apache.org/log4j/" target="_blank">Jakarta Log4J </a></td>
+    <td>Logging Framework des Apache Jakarta Projekts </td>
     </tr>
   <tr>
     <td>&nbsp;</td>