path: root/doc/book/src/cpp-broker/Running-CPP-Broker.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 
-->

<section id="section-Running-a-Qpid-CPP-Broker">
  <title>
    Running a Qpid C++ Broker
  </title>

    <section role="h2" id="RASC-BuildingtheCppBrokerandClientLibraries"><title>
            Building the
            C++ Broker and Client Libraries
          </title>
          <para>
            The root directory for the C++ distribution is named
            qpidc-0.4. The README file in that directory gives
            instructions for building the broker and client libraries. In
            most cases you will do the following:
          </para>
            <programlisting>
[qpidc-0.4]$ ./configure
[qpidc-0.4]$ make
</programlisting>
    <!--h2--></section>
    <section role="h2" id="RASC-RunningtheCppBroker"><title>
            Running the C++ Broker
          </title>
          <para>
            Once you have built the broker and client libraries, you can
            start the broker from the command line:
          </para>
            <programlisting>
[qpidc-0.4]$ src/qpidd
</programlisting>
          <para>
            Use the --daemon option to run the broker as a daemon
            process:
          </para>
            <programlisting>
[qpidc-0.4]$ src/qpidd --daemon
</programlisting>
          <para>
            You can stop a running daemon with the --quit option:
          </para>
            <programlisting>
[qpidc-0.4]$ src/qpidd --quit
</programlisting>
          <para>
            You can see all available options with the --help option
          </para>
            <programlisting>
[qpidc-0.4]$ src/qpidd --help
</programlisting>
    <!--h2--></section>
    <section role="h2" id="RASC-Mostcommonquestionsgettingqpiddrunning"><title>
            Most
            common questions getting qpidd running
          </title>
          <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"><title>
            Error
            when starting broker: "no data directory"
          </title>
          <para>
            The C++ Broker requires you to set a data directory or specify
            --no-data-dir (see help for more details). The data
            directory is used for the journal, so it is important when
            reliability counts. Make sure your process has write permission
            to the data directory.
          </para><para>
            The default location is
          </para>
            <programlisting>
/lib/var/qpidd
</programlisting>
          <para>
            An alternate location can be set with --data-dir
          </para>
	  <!--h3--></section>
	  <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"><title>
            Error
            when starting broker: "that process is locked"
          </title>
          <para>
            Note that when qpidd starts it creates a lock file is data
            directory are being used. If you have a un-controlled exit,
            please mail
            the trace from the core to the dev@qpid.apache.org mailing list.
            To clear the lock run
          </para>
            <programlisting>
./qpidd -q
</programlisting>
          <para>
            It should also be noted that multiple brokers can be run on the
            same host. To do so set alternate data directories for each qpidd
            instance.
          </para>
	  <!--h3--></section>
	  <section role="h3" id="RASC-Usingaconfigurationfile"><title>
            Using a configuration
            file
          </title>
          <para>
            Each option that can be specified on the command line can also be
            specified in a configuration file. To see available options, use
            --help on the command line:
          </para>
            <programlisting>
./qpidd --help
</programlisting>
          <para>
            A configuration file uses name/value pairs, one on each line. To
            convert a command line option to a configuration file entry:
          </para><para>
            a.) remove the '--' from the beginning of the option.
            b.) place a '=' between the option and the value (use
            <emphasis>yes</emphasis> or <emphasis>true</emphasis> to enable options that take no
            value when specified on the command line).
            c.) place one option per line.
          </para><para>
            For instance, the --daemon option takes no value, the
            --log-to-syslog option takes the values yes or
            no. The following configuration file sets these two
            options:
          </para>
            <programlisting>
daemon=yes
log-to-syslog=yes
</programlisting>
	  <!--h3--></section>
          <section role="h3" id="RASC-CanIuseanyLanguageclientwiththeCppBroker-3F"><title>
            Can I use
            any Language client with the C++ Broker?
          </title>
          <para>
            Yes, all the clients work with the C++ broker; it is written in
            C+<emphasis>, but uses the AMQP wire protocol. Any broker can be used
            with any client that uses the same AMQP version. When running the
            C</emphasis>+ broker, it is highly recommended to run AMQP 0-10.
          </para><para>
            Note that JMS also works with the C++ broker.
          </para>
	  <!--h3--></section>
	<!--h2--></section>
	  <section role="h2" id="RASC-Authentication"><title>
            Authentication
          </title>
          <section role="h3" id="RASC-Linux"><title>
            Linux
          </title>
          <para>
            The PLAIN authentication is done on a username+password, which is
            stored in the sasldb_path file. Usernames and passwords can be
            added to the file using the command:
          </para>
            <programlisting>
saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u &lt;REALM&gt; &lt;USER&gt;
</programlisting>
          <para>
            The REALM is important and should be the same as the
            --auth-realm
            option to the broker. This lets the broker properly find the user
            in
            the sasldb file.
          </para><para>
            Existing user accounts may be listed with:
          </para>
            <programlisting>
sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
</programlisting>
          <para>
            NOTE: The sasldb file must be readable by the user running the
            qpidd daemon, and should be readable only by that user.
          </para>
	  <!--h3--></section>
	  <section role="h3" id="RASC-Windows"><title>
            Windows
          </title>
          <para>
            On Windows, the users are authenticated against the local
            machine. You should add the appropriate users using the standard
            Windows tools (Control Panel-&gt;User Accounts). To run many of
            the examples, you will need to create a user "guest" with
            password "guest".
          </para><para>
            If you cannot or do not want to create new users, you can run
            without authentication by specifying the no-auth option to the
            broker.
          </para>
	  <!--h3--></section>
	  <!--h2--></section>

	  <section role="h2" id="RASC-Slightlymorecomplexconfiguration"><title>
            Slightly more
            complex configuration
          </title>
          <para>
            The easiest way to get a full listing of the broker's options are
            to use the --help command, run it locally for the latest set of
            options. These options can then be set in the conf file for
            convenience (see above)
          </para>
            <programlisting>
./qpidd --help

Usage: qpidd OPTIONS
Options:
  -h [ --help ]                    Displays the help message
  -v [ --version ]                 Displays version information
  --config FILE (/etc/qpidd.conf)  Reads configuration from FILE

Module options:
  --module-dir DIR (/usr/lib/qpidd)  Load all .so modules in this directory
  --load-module FILE                 Specifies additional module(s) to be loaded
  --no-module-dir                    Don't load modules from module directory

Broker Options:
  --data-dir DIR (/var/lib/qpidd)   Directory to contain persistent data generated by the broker
  --no-data-dir                     Don't use a data directory.  No persistent
                                    configuration will be loaded or stored
  -p [ --port ] PORT (5672)         Tells the broker to listen on PORT
  --worker-threads N (3)            Sets the broker thread pool size
  --max-connections N (500)         Sets the maximum allowed connections
  --connection-backlog N (10)       Sets the connection backlog limit for the
                                    server socket
  --staging-threshold N (5000000)   Stages messages over N bytes to disk
  -m [ --mgmt-enable ] yes|no (1)   Enable Management
  --mgmt-pub-interval SECONDS (10)  Management Publish Interval
  --ack N (0)                       Send session.ack/solicit-ack at least every
                                    N frames. 0 disables voluntary ack/solitict
                                   -ack

Daemon options:
  -d [ --daemon ]             Run as a daemon.
  -w [ --wait ] SECONDS (10)  Sets the maximum wait time to initialize the
                              daemon. If the daemon fails to initialize, prints
                              an error and returns 1
  -c [ --check ]              Prints the daemon's process ID to stdout and
                              returns 0 if the daemon is running, otherwise
                              returns 1
  -q [ --quit ]               Tells the daemon to shut down
Logging options:
  -t [ --trace ]              Enables all logging
  --log-enable RULE (notice+) Enables logging for selected levels and components. 
                              RULE is in the form 'LEVEL[+-][:PATTERN]'
                              LEVEL is one of: 
                                 trace debug info notice warning error critical
                              PATTERN is a logging category name, or a namespace-qualified 
                              function name or name fragment. 
                                 Logging category names are: 
                                 Security Broker Management Protocol System HA Messaging Store 
                                 Network Test Client Model Unspecified

                              For example:
                                  '--log-enable warning+'
                                  logs all warning, error and critical messages.

                                  '--log-enable trace+:Broker'
                                  logs all category 'Broker' messages.

                                  '--log-enable debug:framing'
                                  logs debug messages from all functions with 'framing' in 
                                  the namespace or function name.

                              This option can be used multiple times

  --log-disable RULE          Disables logging for selected levels and components. 
                              RULE is in the form 'LEVEL[+-][:PATTERN]'
                              LEVEL is one of: 
                                 trace debug info notice warning error critical
                              PATTERN is a logging category name, or a namespace-qualified 
                              function name or name fragment. 
                                 Logging category names are: 
                                 Security Broker Management Protocol System HA Messaging Store 
                                 Network Test Client Model Unspecified

                              For example:
                                  '--log-disable warning-'
                                  disables logging all warning, notice, info, debug, and 
                                  trace messages.

                                  '--log-disable trace:Broker'
                                  disables all category 'Broker' trace messages.

                                  '--log-disable debug-:qmf::'
                                  disables logging debug and trace messages from all functions 
                                  with 'qmf::' in the namespace.

                              This option can be used multiple times

  --log-time yes|no (1)                 Include time in log messages
  --log-level yes|no (1)                Include severity level in log messages
  --log-source yes|no (0)               Include source file:line in log 
                                        messages
  --log-thread yes|no (0)               Include thread ID in log messages
  --log-function yes|no (0)             Include function signature in log 
                                        messages
  --log-hires-timestamp yes|no (0)      Use hi-resolution timestamps in log 
                                        messages
  --log-category yes|no (1)             Include category in log messages
  --log-prefix STRING                   Prefix to prepend to all log messages

Logging sink options:
  --log-to-stderr yes|no (1)            Send logging output to stderr
  --log-to-stdout yes|no (0)            Send logging output to stdout
  --log-to-file FILE                    Send log output to FILE.
  --log-to-syslog yes|no (0)            Send logging output to syslog;
                                        customize using --syslog-name and 
                                        --syslog-facility
  --syslog-name NAME (qpidd)            Name to use in syslog messages
  --syslog-facility LOG_XXX (LOG_DAEMON) 
                                        Facility to use in syslog messages

</programlisting>
	  <!--h2--></section>
          <section role="h2" id="RASC-Loadingextramodules"><title>
            Loading extra modules
          </title>
          <para>
            By default the broker will load all the modules in the module
            directory, however it will NOT display options for modules that
            are not loaded. So to see the options for extra modules loaded
            you need to load the module and then add the help command like
            this:
          </para>
            <programlisting>
./qpidd --load-module libbdbstore.so --help
Usage: qpidd OPTIONS
Options:
  -h [ --help ]                    Displays the help message
  -v [ --version ]                 Displays version information
  --config FILE (/etc/qpidd.conf)  Reads configuration from FILE


 / .... non module options would be here ... /


Store Options:
  --store-directory DIR     Store directory location for persistence (overrides
                            --data-dir)
  --store-async yes|no (1)  Use async persistence storage - if store supports
                            it, enables AIO O_DIRECT.
  --store-force yes|no (0)  Force changing modes of store, will delete all
                            existing data if mode is changed. Be SURE you want
                            to do this!
  --num-jfiles N (8)        Number of files in persistence journal
  --jfile-size-pgs N (24)   Size of each journal file in multiples of read
                            pages (1 read page = 64kiB)
</programlisting>
<!--h2--></section>
<section role="h2" id="RASC-message-timestamps">
  <title>Timestamping Received Messages</title>
  <para>
    The AMQP 0-10 specification defines a <emphasis>timestamp</emphasis> message delivery
    property. The timestamp delivery property is a <emphasis>datetime</emphasis> value
    that is written to each message that arrives at the broker.  See the description of
    "message.delivery-properties" in the "Command Classes" section of the AMQP 0-10
    specification for more detail.
  </para>
  <para>
    See the <emphasis>Programming in Apache Qpid</emphasis> documentation for
    information regarding how clients may access the timestamp value in received
    messages.
  </para>
  <para>
    By default, this timestamping feature is disabled.  To enable timestamping, use the
    <emphasis>enable-timestamp</emphasis> broker configuration option.  Setting the
    enable-timestamp option to 'yes' will enable message timestamping:
  </para>
  <programlisting>
./qpidd --enable-timestamp yes
  </programlisting>
  <para>
    Message timestamping can also be enabled (and disabled) without restarting the broker.
    The QMF Broker management object defines two methods for accessing the timestamp
    configuration:
  </para>
  <table>
    <title>QMF Management - Broker Methods for Managing the Timestamp Configuration</title>
    <tgroup cols="2">
      <thead>
        <row>
          <entry>Method</entry>
          <entry>Description</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>getTimestampConfig</entry>
          <entry>Get the message timestamping configuration.  Returns True if received messages are timestamped.</entry>
        </row>
        <row>
          <entry>setTimestampConfig</entry>
          <entry>Set the message timestamping configuration. Set True to enable timestamping received messages, False to disable timestamping.</entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <example>
    <title>Enabling Message Timestamping via QMF - Python</title>
    <para>
      The following code fragment uses these QMF method calls to enable message timestamping.
    </para>
    <programlisting lang="python">
# get the state of the timestamp configuration
broker = self.qmf.getObjects(_class="broker")[0]
rc = broker.getTimestampConfig()
self.assertEqual(rc.status, 0)
self.assertEqual(rc.text, "OK")
print("The timestamp setting is %s" % str(rc.receive))

# try to enable it
rc = broker.setTimestampConfig(True)
self.assertEqual(rc.status, 0)
self.assertEqual(rc.text, "OK")
    </programlisting>
  </example>
<!--h2--></section>
<section role="h2" id="RASC-logging-options">
  <title>Logging Options</title>
  <para>
    The C++ Broker provides a rich set of logging options. To use logging effectively
    a user must select a useful set of options to expose the log messages of interest.
    This section introduces the logging options and how they are used in practice.
  </para>
  <section role="h3" id="RASC-LogConcepts">
    <title>Logging Concepts</title>

    <section role="h4" id="RASC-LogConcept-level">
      <title>Log Level</title>
      <para>
	The C++ Broker has a traditional set of log severity levels. The log levels
	range from low frequency and high importance critical level
	to high frequency and low importance trace level.
      </para>
      <table>
	<title>C++ Broker Log Severity Levels</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Level</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row><entry>critical</entry><entry>high</entry></row>
	    <row><entry>error</entry>   <entry></entry>    </row>
	    <row><entry>warning</entry> <entry></entry>    </row>
	    <row><entry>notice</entry>  <entry></entry>    </row>
	    <row><entry>info</entry>    <entry></entry>    </row>
	    <row><entry>debug</entry>   <entry></entry>    </row>
	    <row><entry>trace</entry>   <entry>low</entry> </row>
	  </tbody>
	</tgroup>
      </table>
    <!--h4--></section>

    <section role="h4" id="RASC-LogConcept-category">
      <title>Log Category</title>
      <para>
	The C++ Broker groups log messages into categories. The log category
	name may then be used to enable and disable groups of related messages
	at varying log levels.
      </para>
      <table>
	<title>C++ Broker Log Categories</title>
	<tgroup cols="1">
	  <thead>
	    <row>
	      <entry>Name</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row><entry>Security</entry></row>
	    <row><entry>Broker</entry></row>
	    <row><entry>Management</entry></row>
	    <row><entry>Protocol</entry></row>
	    <row><entry>System</entry></row>
	    <row><entry>HA</entry></row>
	    <row><entry>Messaging</entry></row>
	    <row><entry>Store</entry></row>
	    <row><entry>Network</entry></row>
	    <row><entry>Test</entry></row>
	    <row><entry>Client</entry></row>
	    <row><entry>Model</entry></row>
	    <row><entry>Unspecified</entry></row>
	  </tbody>
	</tgroup>
      </table>
      <para>
	Generally speaking the log categories are groupings of messages from files 
	related by
	thier placement in the source code directory structure. The 
	<emphasis>Model</emphasis> category is an exception. Debug log entries 
	identified by the Model category expose the creation, deletion, and usage 
	statistics for managed objects in the broker. Log messages in the Model 
	category are emitted by source files scattered throughout the source tree.
      </para>
    <!--h4--></section>

    <section role="h4" id="RASC-LogConcept-StatementAttributes">
      <title>Log Statement Attributes</title>
      <para>
	Every log statement in the C++ Broker has fixed attributes that may be
	used in enabling or disabling log messages.
      </para>
      <table>
	<title>C++ Broker Log Statement Attributes</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>Level</entry>
	      <entry>Severity level</entry>
	    </row>
	    <row>
	      <entry>Category</entry>
	      <entry>Category</entry>
	    </row>
	    <row>
	      <entry>Function</entry>
	      <entry>Namespace-qualified source function name</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

    <!--h4--></section>

  <!--h3--></section>
  <section role="h3" id="RASC-LogRules-EnableDisable">
    <title>Enabling and Disabling Log Messages</title>
    <para>
      The Qpid C++ Broker has hundreds of log message statements in the source
      code. Under typical conditions
      most of the messages are deselected and never emitted as actual logs.
      However, under some circumstances debug and trace messages must be enabled
      to analyze broker behavior. This section discusses how the broker enables
      and disables log messages.
    </para>
    <para>
      At startup the broker processes command line and option file '--log-enable RULE' and
      '--log-disable RULE' options using the following rule format:
    </para>
    <programlisting>
  LEVEL[+-][:PATTERN}
    </programlisting>
    <table>
      <title>C++ Broker Log Enable/Disable RULE Format</title>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Name</entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>LEVEL</entry>
	    <entry>Severity level</entry>
	  </row>
	  <row>
	    <entry>[+-]</entry>
	    <entry>
	      Option level modifiers. <emphasis>'+'</emphasis> indicates 
	      <emphasis>this level and above</emphasis>. 
	      <emphasis>'-'</emphasis> indicates <emphasis>this level and below</emphasis>.
	    </entry>
	  </row>
	  <row>
	    <entry>[:PATTERN]</entry>
	    <entry>
	      If PATTERN matches a Category name then the log option applies only
	      to log messages with the named category. Otherwise, the pattern is stored
	      as a function name match string.
	    </entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    <para>
      As the options are procesed the results are aggregated into two pairs of tables.
    </para>
    <table>
      <title>C++ Broker Log Enable/Disable Settings Tables</title>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Name</entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>Function Table</entry>
	    <entry>
	      A set of vectors of accumulated function name patterns. 
	      There is a separate vector of name patterns for each log level.
	    </entry>
	  </row>
	  <row>
	    <entry>Category Table</entry>
	    <entry>
	      A simple two dimensional array of boolean values indexed by 
	      [Level][Category] indicating
	      if all log statements are enabled for the Level and Category pair.
	    </entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    <para>
      --log-enable statements and --log-disable statements are aggregated into dedicated
      Function and Category tables. With this scheme multiple conflicting log enable and
      disable commands may be processed in any order yet produce consistent patterns
      of enabled broker log statements.
    </para>
  <!--h3--></section>

  <section role="h3" id="RASC-LogRules-RuleMatching">
    <title>Determining if a Log Statement is Enabled</title>
    <para>
      Function Table Lookups are simple string pattern matches where the searchable
      text is the domain-name qualified function name from the log statement and the
      search pattern is the set of Function Table entries for a given log level.
    </para>
    <para>
      Category Table Lookups are boolean array queries where the Level and Category 
      indexes are from the log statement.
    </para>
    <para>
      Each log statment sends its Level, Category, and FunctionName to the
      Logger for evaluation. As a result the log statement is either visible or hidden.
    </para>
    <table>
      <title>C++ Broker Log Statement Visibility Determination</title>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Test</entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>Disabled Function</entry>
	    <entry>
	      If the statement matches a Disabled Function pattern then the
	      statement is hidden.
	    </entry>
	  </row>
	  <row>
	    <entry>Disabled Category</entry>
	    <entry>
	      If the Disabled Category table for this [Level][Category] is true then the
	      statement is hidden.
	    </entry>
	  </row>
	  <row>
	    <entry>Enabled Function</entry>
	    <entry>
	      If the statement matches a Enabled Function pattern then the
	      statement is visible.
	    </entry>
	  </row>
	  <row>
	    <entry>Enabled Category</entry>
	    <entry>
	      If the Enabled Category table for this [Level][Category] is true then the
	      statement is visible.
	    </entry>
	  </row>
	  <row>
	    <entry>Unreferenced</entry>
	    <entry>
	      Log statements that are unreferenced by specific enable rules are by 
	      default hidden.
	    </entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  <!--h3--></section>

  <section role="h3" id="RASC-LogRules-Reenabling">
    <title>Changing Log Enable/Disable Settings at Run Time</title>
    <para>
      The C++ Broker provides QMF management methods that allow users to query and to set
      the log enable and disable settings while the broker is running.
    </para>
    <table>
      <title>QMF Management - Broker Methods for Managing the Log Enable/Disable Settings</title>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Method</entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>getLogLevel</entry>
	    <entry>Get the log enable/disable settings.</entry>
	  </row>
	  <row>
	    <entry>setLogLevel</entry>
	    <entry>Set the log enable/disable settings.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    <para>
      The management methods use a RULE format similar to the option RULE format:
    </para>
    <programlisting>
  [!]LEVEL[+-][:PATTERN]
    </programlisting>
    <para>
      The difference is the leading exclamation point that identifies disable rules.
    </para>
    <example>
      <title>
	Querying Log Settings via qpid-ctrl utility
      </title>
      <para>
	At start up a C++ Broker may have the following options:
      </para>
      <programlisting>
  --log-enable debug+
  --log-enable trace+:Protocol
  --log-disable info-:Management
      </programlisting>
      <para>
	The following command:
      </para>
      <programlisting>
  qpid-ctrl getLogLevel
      </programlisting>
      <para>
	will return the following result:
      </para>
      <programlisting>
  level=debug+,trace+:Protocol,!info-:Management
      </programlisting>
    </example>
    <example>
      <title>
	Setting Log Settings via qpid-ctrl utility
      </title>
      <para>
	New broker log options may be set at any time using qpid-ctrl
      </para>
      <programlisting>
  qpid-ctrl setLogLevel level='debug+:Broker !debug-:broker::Broker::ManagementMethod'
      </programlisting>
    </example>
  <!--h3--></section>

  <section role="h3" id="RASC-LogRules-Explorer">
    <title>Discovering Log Sources</title>
    <para>
      A common condition for a user is being swamped by log messages that are not
      interesting for some debug situation. Conversely, a particular log entry
      may be of interest all the time but enabling all log levels just to see a
      single log entry is too much. How can a user find and specify a pattern
      to single out logs of interest?
    </para>
    <para>
      The easiest way to hide messages it to disable logs at log level and 
      category combinations. This may not always work since using only these 
      coarse controls the log messages of interest may also be hidden. 
      To discover a more precise filter to specify the messages you want 
      to show or to hide you may temporarily enable the 
      <emphasis>"--log-function=yes"</emphasis> option. 
      The following log entries show a typical log message without and 
      with the log function names enabled:
    </para>
    <programlisting>
  2013-05-01 11:16:01 [Broker] notice Broker running
  2013-05-01 11:16:54 [Broker] notice qpid::broker::Broker::run: Broker running
    </programlisting>
    <para>
      This log entry is emitted by function <emphasis>qpid::broker::Broker::run</emphasis>
      and this is the function name pattern to be used in specific log enable and 
      disable rules.
      For example, this log entry could be disabled with any of the following:
    </para>
    <programlisting>
  --log-disable notice                            [1]
  --log-disable notice:qpid::                     [2]
  --log-disable notice:Broker                     [3]
  --log-disable notice-:Broker::run               [4]
  --log-disable notice:qpid::broker::Broker::run  [5]
    </programlisting>
    <itemizedlist>
      <listitem>
	[1] Disables all messages at notice level.
      </listitem>
      <listitem>
	[2] Disables all messages at notice level in qpid:: name space. This is
	very broad and disables many log messages.
      </listitem>
      <listitem>
	[3] Disables the category <emphasis>[Broker]</emphasis> and is not specific
	to the function. Category names supercede function name fragments in
	log option processing
      </listitem>
      <listitem>
	[4] Disables the function.
      </listitem>
      <listitem>
	[5] Disables the function.
      </listitem>
    </itemizedlist>
    <para>
      Remember that the log filter matching PATTERN strings are matched against the 
      domain-name qualified function names associated with the log statement
      and not against the log message text itself. That is, in the previous example
      log filters cannot be set on the log text <emphasis>Broker running</emphasis>
    </para>
  <!--h3--></section>
<!--h2--></section>
</section>