Server

Automation Tracing

Updated: March 18, 2024

Automation chains and operations calls information is collected during their execution by the Automation Trace feature.

This Automation trace mode can be enabled through the nuxeo.conf file properties:

Property Default value Description
org.nuxeo.automation.trace false - You'll benefit from exhaustive logs to debug all automation chain and/or operation execution.
- The automation trace mode is disabled by default (not suitable for production).
- It can be activated through JMX via org.nuxeo:TracerFactory MBean during runtime.
org.nuxeo.automation.trace.printable * By default, all automation executions are 'printable' (appear in logs) when automation trace mode is on.
- You can filter chain and/or operation execution trace printing by setting this property to chain name and/or operation separated by comma.
- Comment this property to get all automation chains/operations back in printing (by default set to * (star))

To display traces even for executions without errors, this appender is added by default in your nuxeo-***-tomcat/lib/log4j configuration file:

<category name="org.nuxeo.ecm.automation.core">
  <priority value="INFO" />
</category>

Examples: Simple chain
****** chain ******
Name: chainA
Produced output type: DocumentModelImpl

****** Context.FetchDocument ******
Chain ID: chainA
Class: FetchContextDocument
Method:
 'run' | Input Type: interface org.nuxeo.ecm.core.api.DocumentModel |
Output Type: interface org.nuxeo.ecm.core.api.DocumentModel
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Context Variables | Key: ChainParameters, Value: {}

****** Seam.AddInfoMessage ******
Chain ID: chainA
Class: AddInfoMessage
Method: 'run' | Input Type: void | Output Type: void
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Parameters  | Name: message, Value: Message INFO
Context Variables | Key: ChainParameters, Value: {}
  • 'chainA' is executed, produces a document model and runs two operations: Context.FetchDocument and Seam.AddInfoMessage .
  • These two operations display the following information during their executions:

    • Input Type, Output Type,
    • The Input (here the 'default-domain' document),
    • Parameters defined into each operation with their values,
    • Context Variables (injected during execution).
Examples: Composite Chains
****** chain ******
Name: chainA
Produced output type: DocumentModelImpl

****** Context.FetchDocument ******
Chain ID: chainA
Class: FetchContextDocument
Method:
 'run' | Input Type: interface org.nuxeo.ecm.core.api.DocumentModel |
Output Type: interface org.nuxeo.ecm.core.api.DocumentModel
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Context Variables | Key: ChainParameters, Value: {}

****** Context.RunOperation ******
Chain ID: chainA
Class: RunOperation
Method: 'run' | Input Type: void | Output Type: void
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Parameters  | Name: id, Value: chainB | Name: isolate, Value: false
Context Variables | Key: ChainParameters, Value: {}

****** start sub chain ******

****** chain ******
Parent Chain ID: chainA
Name: chainB
Produced output type: DocumentModelImpl

****** Context.FetchDocument ******
Chain ID: chainB
Class: FetchContextDocument
Method:
 'run' | Input Type: interface org.nuxeo.ecm.core.api.DocumentModel |
Output Type: interface org.nuxeo.ecm.core.api.DocumentModel
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Context Variables | Key: ChainParameters, Value: {}

****** Seam.AddInfoMessage ******
Chain ID: chainB
Class: AddInfoMessage
Method: 'run' | Input Type: void | Output Type: void
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Parameters  | Name: message, Value: Message INFO
Context Variables | Key: ChainParameters, Value: {}

****** end sub chain ******

****** Seam.AddInfoMessage ******
Chain ID: chainA
Class: AddInfoMessage
Method: 'run' | Input Type: void | Output Type: void
Input: DocumentModelImpl(5eff3564-1a69-4d91-ae0c-51fb879a6a5a, path=/default-domain, title=Default domain)
Parameters  | Name: message, Value: test
Context Variables | Key: ChainParameters, Value: {} | Key: Seam.AddInfoMessage, Value: Message INFO
  • 'chainA' is executed, produces a document model and runs three operations: Context.FetchDocument, Context.RunOperation and Seam.AddInfoMessage.
  • The Context.RunOperation runs a second subchain 'chainB':

    • These chain has parent ID attribute to 'chainA';
    • It contains two operations: Context.FetchDocument and Seam.AddInfoMessage;
    • At subchain ending, third Seam.AddInfoMessage operation contained into 'chainB' is executed.
JMX Automation Trace Activation

The Automation Trace mode can be activated through JMX via org.nuxeo:TracerFactory MBean during runtime.

You can also activate the traces (and download them for each chain) from the dynamical documentation of Automation module : http://NUXEO_SERVER/nuxeo/site/automation/doc (you should adapt server name and port number).

Please follow guidelines to activate it:

  1. Install the VisualVM MBean plugin
  2. Run VisualVM and connect it to the Nuxeo server.
  3. Look for the MBean org.automation.trace.TracerFactory to access to several services.

    • 'clearTraces' to clean up traces collected during execution.
    • 'toggleRecording' to enable/disable automation trace mode.
    • 'setPrintableTraces' to filter on several chains to print.

Traces are collected and cached for one hour.