From b83163b9a83f347855ad28eb5128abf2f5035500 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 28 May 2013 15:31:47 +0000
Subject: [PATCH] CR-1749 Fix for OPENDJ-924: Document howto enable stack traces

---
 opendj3/src/main/docbkx/admin-guide/chap-troubleshooting.xml |   88 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 88 insertions(+), 0 deletions(-)

diff --git a/opendj3/src/main/docbkx/admin-guide/chap-troubleshooting.xml b/opendj3/src/main/docbkx/admin-guide/chap-troubleshooting.xml
index 6bcb95b..06a1af7 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-troubleshooting.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-troubleshooting.xml
@@ -198,6 +198,94 @@
   </procedure>
  </section>
 
+ <section xml:id="troubleshoot-enable-debug-logging">
+  <title>Enabling Debug Logging</title>
+  <indexterm><primary>Debug log</primary></indexterm>
+  <indexterm>
+   <primary>Logs</primary>
+   <secondary>Debug</secondary>
+  </indexterm>
+
+  <para>OpenDJ can write debug information and stack traces to the server
+  debug log. What is logged depends both on debug targets that you create,
+  and also on the debug level that you choose.</para>
+
+  <procedure xml:id="configure-debug-logging">
+   <title>To Configure Debug Logging</title>
+
+   <step>
+    <para>Enable the debug log, <filename>opendj/logs/debug</filename>, which
+    is not enabled by default.</para>
+
+    <screen>$ dsconfig
+ set-log-publisher-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --set enabled:true
+ --set default-debug-level:all
+ --no-prompt
+ --trustAll</screen>
+
+    <para>You can set <literal>default-debug-level</literal> to a less verbose
+    level if necessary.</para>
+   </step>
+
+   <step>
+    <para>Create a debug target or targets.</para>
+
+    <para>No debug targets are enabled by default.</para>
+
+    <screen>$ dsconfig
+ list-debug-targets
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --no-prompt
+ --trustAll
+
+Debug Target : debug-level : debug-category
+-------------:-------------:---------------
+
+$ </screen>
+
+    <para>A debug target specifies a fully-qualified OpenDJ Java package,
+    class, or method for which to log debug messages at the level you
+    specify.</para>
+
+    <screen>$ dsconfig
+ create-debug-target
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --type generic
+ --target-name org.opends.server.api
+ --set debug-level:all
+ --no-prompt
+ --trustAll</screen>
+   </step>
+
+   <step>
+    <para>Restart OpenDJ to see debug messages in the log.</para>
+
+    <screen>$ /path/to/opendj/bin/stop-ds --restart
+...
+$ tail -f /path/to/opendj/logs/debug
+...</screen>
+
+    <para>If you have set <literal>debug-level:all</literal>, OpenDJ generates
+    a great deal of output in the debug log file. Use debug logging very
+    sparingly on production systems.</para>
+   </step>
+  </procedure>
+ </section>
+
  <section xml:id="troubleshoot-use-lockdown-mode">
   <title>Preventing Access While You Fix Issues</title>
   <indexterm><primary>Lockdown mode</primary></indexterm>

--
Gitblit v1.10.0