To trace exchange activities into files, it is better to have a policy based on one log file per process instance instead of having one big file. One file by process instance is more human readable. So a new file handler is also provided: [{{org.ow2.petals.log.handler.PetalsFileHandler}}|#petals_file_handler].
The MONIT level permits also to dump the message exchange content using another dedicated file handler: [{{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}}|#petals_dumper_file_handler]. It is based on the file handler '{{org.ow2.petals.log.handler.PetalsFileHandler}}' adding it capabilities to dump the payload of message exchanges.
h2. Default levels
The default root logger level is WARNING. It means that all classes log only SEVERE and WARNING information.
The default Petals root logger level is INFO. That's why all Petals components will log only SEVERE, WARNING and INFO information.
The default components level is MONIT.
You can enable logging and specify a specific level for each module (container, component, cdk...). Here is how you would set debugging from Petals. You would need to ensure the Handler's level is also set to collect this threshold, so FINEST or ALL should be set.
{code}
##Petals level
Petals.level = FINEST
#Handler Configuration
java.util.logging.ConsoleHandler.level = FINEST
{code}
Example of configuration to debug (Level FINEST) petals-bc-soap component:
{code}
##Petals level
Petals.level = INFO #Log level for all petals services
Petals.Container.Components.level = MONIT #log level for all components
Petals.Container.Components.petals-bc-soap.level = FINEST #Log level for petals-bc-soap component
#Handler Configuration
java.util.logging.ConsoleHandler.level = FINEST
{code}
{anchor:petals_formatter}
h2. Petals formatter
The Petals formatter {{org.ow2.petals.log.formatter.LogDataFormatter}} is used for both standard traces of the Petals ESB container and process activity traces. The format of the logged message is :
{panel:borderStyle=solid}+Petals Node Name+ +YYYY/MM/DD+ +HH:MM:SS,FFF+ +GMT+ +LOG LEVEL+ [+LOGGER NAME+] : +LOG MESSAGE+{panel}
For a process activity, the log message is composed of several fields as key/value depending on the JBI component and activity. See [Monitoring Petals ESB Flows with its logs] for more information on fields.
*Example of logging output with the Petals formatter:*
{code}
sample-0 2013/03/07 10:31:31,084 GMT+0100 INFO [Petals.Communication.RMIConnector] : JMX RMI server started at : service:jmx:rmi:///jndi/rmi://localhost:7700/jmxRmiConnector
...
sample-0 2013/03/07 10:31:32,459 GMT+0100 MONIT [Petals.Container.Components.petals-bc-soap] : traceCode = 'consumeFlowStepBegin',flowInstanceId = '62cdea40-cf20-11e0-bdfa-000c29523cc7',flowStepId = '62ce3860-cf20-11e0-bdfa-000c29523cc7',flowInterfaceName = '{[http://usecase1/bpel-P12/]}interfaceName1',flowServiceName = '{[http://usecase1/bpel-P12/]}serviceName1',flowEndpointName = 'endpointName1',flowOperationName = '{[http://usecase1/bpel-P12/]}process',client = '192.168.1.157',requestedURL = 'http://192.168.1.196:8084/petals/services/soap-C1'
{code}
{anchor:petals_file_handler}
h2. Splitting log files
Petals ESB allow to split its log records into a log files hierarchy. Thanks to the Petals file handler '{{org.ow2.petals.log.handler.PetalsFileHandler}}' which can redirect log records to separate files according to their nature:
* if the log record is generated into a process activity context, it is redirected in the log file dedicated to the process instance,
* otherwise, the log record is sent into the global log file.
{anchor:log_file_hierarchy}
The default log files hierarchy is the following one:
* basedir
** petals.log: The global log file in which log records that are not generated into a process activity context are logged,
** flow-monitoring: Directory in which log files of log records associated to process activities are written,
*** <uid>: Directory of log files associated to the activities of only *ONE* process instance,
**** petals.log: The log file of process activities of only *ONE* process instance.
In addition to the standard properties ({{level}} and {{formatter}}), the specific configuration properties of the Petals file handler are:
|| Property || Default value || Description ||
| {{xxx.basedir}} | The value of the system property '{{petals.log.dir}}' | The *absolute* root directory of the log file hierarchy |
| {{xxx.flows-subdir}} | {{flow-monitoring}} | The name of the directory contained in the directory {{basedir}} where log files of log records associated to process activities are written. If the value is a relative, it will be relative to the base directory. Absolute value is accepted. |
| {{xxx.logFilename}} | {{petals.log}} | The name of log files. It's a relative filename value, without directory |
where {{xxx}} is the name of the log handler: {{org.ow2.petals.log.handler.PetalsFileHandler}} or {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}}.
{tip}The Petals file handler processes all log record according to their log level and its own log level. So splitted files can be generated containing only traces with log level SEVERE, WARNING or INFO when the min log level is set to INFO. To have *no splitted files* (ie. no traces about process execution), you must *disable the Petals log handler*, and add the default log file handler of the JDK logging system {{java.util.logging.FileHandler}} to retain a global log file:
{code}
handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler
java.util.logging.ConsoleHandler.level=FINEST
java.util.logging.ConsoleHandler.formatter=org.ow2.petals.log.formatter.LogDataFormatter
java.util.logging.FileHandler.level=FINEST
java.util.logging.FileHandler.pattern=%h/petals-esb-enterprise-edition/petals-esb/logs/petals.log
java.util.logging.FileHandler.formatter=org.ow2.petals.log.formatter.LogDataFormatter
...
{code}
{tip}
{anchor:petals_dumper_file_handler}
h2. Debuging process execution
In the previous paragraph, you see how to get traces about process instance executions. For a debugging or replaying purpose, it is interesting to get the content of messages exchanged. This is possible using another Petals file log handler: {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}} based on the previous file log handler {{org.ow2.petals.log.handler.PetalsFileHandler}}.
The content of the messages are dumped in the log files hierarchy defined [above|#log_file_hierarchy] in the directory dedicated to the current process instance. One dump file is created for each message sent or received containing its XML payload. The path of the dump file is logged, if possible as a relative path to {{basedir}}, in the MONIT trace through a dedicated field: {{payloadContentDumpFile}}.
This Petals file log handler {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}} has the same configuration properties than its [parent|#petals_file_handler] and extends it with the following parameters:
|| Property || Default value || Description ||
| {{xxx.dump-basedir}} | The default value is the flows sub-directory | The name of a root directory that will contain all dump files organized by flow using an intermediate sub directory associated to the flow. If the value is a relative, it will be relative to the flows sub-directory. Absolute value is accepted. |
where {{xxx}} is the name of the log handler: {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}}.
{note}An issue JIRA already exists to dump the whole content of messages, including properties and attachments: {jira:PETALSESBCONT-228}{note}
h2. Using your own log handler
Since the version 4.2 of Petals ESB, custom log handlers are supported. See the [source project code of Petals provided log handlers|https://anonymous:anonymous@svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/tools-commons/petals-log] to write your own.
If you want redirect the MONIT traces elsewhere than into log files, you can use your own log handler. Just put its JAR file and dependencies into the Petals library directory, and configure your log handler into the logging configuration file.
h2. Enabling logging traces of the JMX server
To enable logging traces of the Petals Container JMX server (MX4J), uncomment the property '{{mx4j.log.priority}}' in the environment configuration file:
{code}
# Uncomment following line to enable logging of the JMX Server of Petals
# Available priorities are: trace, debug, info, warn, error, fatal
PETALS_JAVA_OPTS="$PETALS_JAVA_OPTS -Dmx4j.log.priority=debug"
{code}
Possible values for the property are: {{fatal}}, {{error}}, {{warn}}, {{info}}, {{debug}}, {{trace}}
h1. Tuning your logging configuration
If your Petals ESB containers used in production are:
* installed on Debian-based systems through Debian packages,
* and, running in [automatic mode|Starting and stopping Petals ESB installed by Debian packages],
you can disable the log handler 'console' for which all generated traces on the standard output are discarded, and used only a log handler 'file' ({{java.util.logging.FileHandler}}, {{org.ow2.petals.log.handler.PetalsFileHandler}} or {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}} according to your needs about the [flow monitoring|Monitoring Petals ESB Flows with its logs]).
{code}
# Configuration of the log handlers
#####################################
#handlers=java.util.logging.ConsoleHandler, org.ow2.petals.log.handler.PetalsFileHandler
handlers=org.ow2.petals.log.handler.PetalsFileHandler
{code}
\\
If your Petals ESB installation does not satisfy the previous criteria (not running in automatic mode on a Debian-based system), you can improve performance decreasing the level of the log handler 'console':
{code}
# Configuration of the handler ConsoleHandler
##################################################
java.util.logging.ConsoleHandler.level=INFO
java.util.logging.ConsoleHandler.formatter=org.ow2.petals.log.formatter.LogDataFormatter
{code}
You can also remove the log handler 'console' but it's disturbing because no more trace will be printed.
h1. Known problems
h2. No trace more precise than INFO level are logged in the log file
*Operating system:* Debian-based Linux
*Symptoms:*
* Petals ESB is installed with the Debian packages,
* A Petals ESB container is started through the [automatic startup|Starting and stopping Petals ESB installed by Debian packages] ({{sudo service petals-esb start}}), or when booting the host,
* The log configuration file defines level FINEST for JBI component, or equivalent,
* No trace with level FINEST are flushed in the global log file ({{/var/log/petals-esb/<container-name>/petals.log}})
*Solutions to try:*
* Change the log level of the log handler {{org.ow2.petals.log.handler.PetalsFileHandler}} or {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}} and set it the value FINEST.
*Explanations:*
By default, the log configuration set a log level FINEST to the log handler 'console', and the standard output of Petals ESB container is redirected to {{/dev/null}} by the SysV init.
The global log file is the file generated by the log handler {{org.ow2.petals.log.handler.PetalsFileHandler}} or {{org.ow2.petals.log.handler.PetalsPayloadDumperFileHandler}}.