There are two categories that you can enable in the log4j.xml configuration file that allows you to trace what messages are being set by the agent and received by the agent. In the log4j.xml, set the following two categories to TRACE as you see below:
<!-- RHQ outgoing command tracing - set to TRACE to trace commands sent by the agent -->
<category name="org.rhq.enterprise.communications.command.client.OutgoingCommandTrace">
<priority value="TRACE"/>
<appender-ref ref="COMMANDTRACE"/>
</category>
<!-- RHQ incoming command tracing - set to TRACE to trace commands coming in from the Server -->
<category name="org.rhq.enterprise.communications.command.server.IncomingCommandTrace">
<priority value="TRACE"/>
<appender-ref ref="COMMANDTRACE"/>
</category>
This will enable the agent's comm layer to log all sent and received messages to logs/command-trace.log. You do not have to enable both categories if you are only interested in one of the two types of messages (i.e. if you only want to trace outgoing messages because you do not care about the messages the server is sending the agent, just enable TRACE mode for the OutgoingCommandTrace category).
Getting More Details
The logs/command-trace.log can get verbose since it could be logging every message coming and going. However, if you need more information, you have the option of setting one, some or all of the following system properties in the agent thus making the log messages more verbose with additional information:
|
System Property
|
Description
|
|
rhq.trace-command-config
|
If this is set to true, each command's configuration properties will be logged. This will include the agent's token string and other details that are typically considered "out-of-band" of the actual command.
|
|
rhq.trace-command-response-results
|
If set, this will log the results object that is found in successful command responses. The value of this system property should be the maximum length of the string to be logged (since some results objects may have a long toString() representation, this helps trim the size of the log messages). A typical value is 256.
|
|
rhq.trace-command-size-threshold
|
If set, this is the maximum size of commands that can flow into and out of the comm layer without generating a warning message in the log. If a command is larger than this value (defined in bytes), a WARN level message will be logged in logs/command-trace.log. If this is set, this also will generate ERROR level messages if the command is not serializable.
|
|
rhq.trace-command-response-size-threshold
|
If set, this is the maximum size of command responses that can flow into and out of the comm layer without generating a warning message in the log. If a command response is larger than this value (defined in bytes), a WARN level message will be logged in logs/command-trace.log. If this is set, this also will generate ERROR level messages if the response is not serializable.
|
You can turn on and off these system properties while the agent is running by using the setconfig command:
setconfig rhq.trace-command-config=true
setconfig rhq.trace-command-response-results=256
setconfig rhq.trace-command-size-threshold=99999
setconfig rhq.trace-command-response-size-threshold=99999
If you want to set them at startup, you can pass them to the agent via the -D command line argument:
rhq-agent.sh -Drhq.trace-command-config=true -Drhq.trace-command-response-results=256 ...
Again, you do not have to use any of these system property settings. You can set one or more as your needs fit (you do not have to set any of them either, if you do not want to).
You can use the agent prompt command debug --comm=true to turn on this tracing with a set of default rhq.trace-command sysprop settings.
RHQ Server Communications Debugging
The ability to trace commands being sent and received is built into the comm layer. Since both agent and server use the same comm layer, this ability to trace commands can be enabled on the RHQ Server too. The standalone-full.xml file is not preconfigured to perform this tracing, however, you need to only set the categories mentioned above to the TRACE level in the subsystem <subsystem xmlns="urn:jboss:domain:logging:1.1"> in that configuration file. It is recommended that you use an appender to dump the trace messages in another log file (different from the normal server log file). See the agent's log4j.xml file for an example of this. Because the server is talking to many agents, be prepared for very, very large trace files if you enable this on an RHQ Server.