| <?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 <REALM> <USER> |
| </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->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> |
