<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="logging">
    <title>Logging</title>
    <section>
        <title>General Configuration</title>
        <para>(TODO)</para>
    </section>
    <section>
        <title>Verbose Logging</title>
        <para>Some log messages are disabled by default as they produce large amounts of output, and
            are only needed in special circumstances (typically, for debugging). This is called
            "verbose logging", and is controlled by the <code>DebugSettings</code> utility class.
            Typical usage is to initialize a final (static or non-static) field in the logging class
            with the returned setting, to only incur the configuration checking overhead
            once:</para>
        <para><itemizedlist>
                <listitem>
                    <para>non-static field (preferred in most cases, as there is no risk of
                        copying/pasting with the wrong class parameter): <code>private final boolean
                            verboseLogging =
                            DebugSettings.getVerboseLoggingEnabled(getClass());</code></para>
                </listitem>
                <listitem>
                    <para>static field / constant (preferred for classes that are instantiated very
                        frequently): <code>private static final boolean VERBOSE_LOGGING =
                            DebugSettings.getVerboseLoggingEnabled(TheClassName.class);</code></para>
                </listitem>
            </itemizedlist>To control the verbose logging, set the <code>rce.verboseLogging</code>
            system property. Example: <code>rce -p myProfile -vmargs
                -Drce.verboseLogging=*.NodePropertiesServiceImpl,*Workflow*</code>. The syntax of
            the pattern is a comma-separated list of identifiers. A "*" wildcard matches any part of
            the class name, including the dot ("."). An empty string disables all verbose logging.<note>
                <para>As with any other JVM property, this parameter must be placed behind the
                        <code>-vmargs</code> delimiter, which separates it from the "direct" RCE
                    command-line arguments (like <code>--headless</code> or <code>-p
                        &lt;profile></code>). This rule also applies when adding this parameter to
                    an <code>rce.ini</code> file.</para>
            </note></para>
        <para>If this system property is not set, the
                <code>DebugSettings.DEFAULT_VERBOSE_LOGGING_PATTERN</code> constant's value is used.
            While developing in Eclipse, it can be useful to enter a verbose logging pattern there,
            as this affects all local RCE instances at once without editing multiple launch
            configurations. (As usual, it is your responsibility to make sure these local debug
            values are not commited into version control.)</para>
        <para>Identifiers created before 8.1.0 were fully qualified Java class names; since 8.1.0,
            identifiers are arbitrary strings. For existing identifiers, these strings were set to
            the pre-8.1.0 FQNs. Over time, all existing identifiers are planned to be migrated to
            more intuitive strings.</para>
        <para>The following table lists some identifiers that may be useful for debugging:<table
                frame="all">
                <title>Useful Verbose Logging Identifiers</title>
                <tgroup cols="2">
                    <colspec colname="c1" colnum="1" colwidth="1.0*"/>
                    <colspec colname="c2" colnum="2" colwidth="1.0*"/>
                    <thead>
                        <row>
                            <entry>Identifier</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>NetworkRequests</entry>
                            <entry>outgoing and received network requests and responses, and
                                possibly other related operations (e.g. conversions)</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table></para>
    </section>
</section>
