{section}
{column}

h1. Introduction

When a request incomes into Petals ESB through a service invocation on a binding component, it fires several other service invocations. All these service invocations form a *flows* or a *process*. Petals ESB provides a mechanism to rebuild these flows or processes executed from an entry point.

This mechanism is based on standard logs. Traces are logged on each input/output of services that are the flow/process steps.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. An example

The default directory for Petals ESB log files is {{$PETALS_HOME}}/logs (you can change logs directory and logs level by following the related configuration documentation). This directory is shared between:
* the petals.log file which holds all informations about bus runtime (bus starting, installing or removing a component, etc);
* a flowMonitoring directory.

The flowMonitoring directory itself will contain subfolders, each one being named after a flow's flowInstanceId. Each such subfolder will contain a file flow.log which will record all logs relating to this particular flow instance (from INFO to MONIT level, or even FINEST level when active).

Whatever their level and usage, logs names (traces in petals.log and flow.log) are always structured like this:
Petals-node-name Date LEVEL \[loggerName\] : Message
FIXME (Petals-node-name : représente le noeud sur lequel se fait les logs) :

On MONIT level, log messages packs two kind of informations:
* standard parameters for this level (are included in every component)
* specific parameters for some logging component.

h4. Standard parameters

_Parameters included in every trace of MONITORING level_
*traceCode*: (represents) the position of the trace in the flow (confer last paragraph).

*flowInstanceId*: (represents) the id of a flow instance.

*flowStepId*: the unique id of a flow step.

*dumpPath*: path for the directory where the IN or OUT message is saved.

_Parameters included only in starting step's traces (MONIT level)_
{section}
{column}

h6. For a Consume Service

*flowStepInterfaceName*: interface name of the first provide invoked (consume service only).

*flowStepServiceName*: service name of the first provide service invoked (consume service only).

*flowStepOperationName*: operation name of the first provide service invoked (consume service only).
{column}

{column}

h6. For a Provide Service

*traceCode*: (represents) the position of the trace in the flow (confer last paragraph).

*flowStepInterfaceName*: interface name of invoked provide service.

*flowStepServiceName*: service name of invoked provide service.

*flowStepOperationName*: operation name of invoked provide service.

*flowStepEndpointName*: endpoint name of invoked provide service.

*flowPreviousStepId*: flowStepId of service which initiated the call (provide service only). \|
{column}
{section}

Parameters recorded in MONIT level when a step fails (ERROR or FAULT state):

*failureMessage*: content of a fault message or an error message .


h4. Specific parameters

These are all parameters which are recorded when a step is starting. It is varying depending on the component.
The table here under presents these traces, varying on component itself and its configuration (consume or provide).
\\
|| Component || Consume || Provide ||
| bc-soap | *requestedURL*: The URL used by the webservice client to invoke the service | *requestedURL*: The URL of the external webservice invoked |
| bc-mail | *scheme*, *host*, *port*, *user*, *folder* | *emailAddress* |
| bc-sftp | N/A | *patterns*, *folder* |
| bc-ftp | N/A | *patterns*, *folder* |
| bc-filetransfer | *filePath* | *fileName*, *destDirName* |
| bc-sql | N/A | *operationSQL* |
| se-bpel | No specific information | No specific information |
| se-eip | No specific information | No specific information |
| se-validation | N/A | No specific information |
| se-xslt | N/A | No specific information |
| se-quartz | *eventTime* | N/A |
| se-jsr-181 | N/A | No specific information |
\\

Definitions of traceCode:
*consumeFlowStepBegin*: détermine la réception d'une requête extérieur sur un consume.

*consumeFlowStepEnd*: end message sent to consumer (out message, or Acknowledgement - ACK-).

*consumeFlowStepFailure*: defines if a problem occured during step execution (a fault or a technical error).



*provideFlowStepBegin*: record of the fact that a provide service receives a call/request from a consume.

*provideFlowStepEnd*: record of the fact that provide service send the answer (out message or request ACK).

*provideFlowStepExtBegin*: record of the fact that provide service calls another service (external call).

*provideFlowStepExtEnd*: record of the fact that a provide service receives the answer to its external call (FIXME soit la réponse réelle, soit l'accusé réception s'il est possible envoyé par le service extérieur, sinon elle ne sera pas présente) .

*provideFlowStepFailure*: defines if a problem occured during step execution (a fault or a technical error).


h1. Dumping content of message payload

When you activate the log handler {{PetalsPayloadDumperFileHandler}}, the logger saves the messages running through the bus, in corresponding flowInstanceId folder. Each message is named according to the following model:
flowStepId_traceCode.xml.
Once the dump is done, a MONIT level log trace is recorded in the flow.log file, with the following informations: traceCode, flowInstanceId and flowStepId (which are the same as the ones recorded by {{PetalsFileHandler}}) and dumpPath (which tells where the message is actually recorded).