Chapter 14. Logging
The logging mechanism allows you to store information about the execution of a process instance. It is provided by a special event listener that listens to the Process Engine for any relevant events to be logged, so that the information can be stored separately from other non-log information stored either in the server built-in database (h2) or a connected data source using JPA or Hibernate.
The
jbpm-audit module provides the event listener and also allows you to store process-related information directly in a database using JPA or Hibernate. The data of the following entities is stored as follows:
- Process instance as
processinstancelog
- Element instance as
nodeinstancelog
- Variable instance as
variableinstancelog
Table 14.1. Fields of the ProcessInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
end_date
|
The end date of the process instance
|
Yes
|
processid
|
The name (id) of the underlying process
|
Yes
|
processinstanceid
|
The id of the process instance
|
No
|
start_date
|
The start date of the process instance
|
Yes
|
status
|
The status of the process instance
|
Yes
|
parentProcessInstanceId
|
The process instance id of the parent process instance if applicable
|
Yes
|
outcome
|
The outcome of the process instance (details on the process finish, such as error code)
|
Yes
|
Table 14.2. Fields of the NodeInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
log_date
|
The date of the event
|
Yes
|
nodeid
|
The node id of the underlying Process Element
|
Yes
|
nodeinstanceid
|
The id of the node instance
|
Yes
|
nodename
|
The name of the underlying node
|
Yes
|
processid
|
The id of the underlying process
|
Yes
|
processinstanceid
|
The id of the parent process instance
|
No
|
type
|
The type of the event (
0 = enter event, 1 = exit event)
|
No
|
Table 14.3. Fields of the VariableInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
log_date
|
The date of the event
|
Yes
|
processid
|
The name (id) of the underlying process
|
Yes
|
processinstanceid
|
The id of the process instance
|
No
|
value
|
The value of the variable at log time
|
Yes
|
variableid
|
The variable id as defined in the process definition
|
Yes
|
variableinstanceid
|
The id of the variable instance
|
Yes
|
outcome
|
The outcome of the process instance (details on the process finish, such as error code)
|
Yes
|
If neccessary, define your own data model of custom information and use the process event listeners to extract the information.
14.1. Logging events to database
To log an event that occurs on runtime in a Process instance, an Element instance, or a variable instance, you need to do the following:
- Map the Log classes to the data source, so that the given data source accepts the log entries. On Red Hat JBoss EAP, edit the data source properties in the
persistence.xml
file.Example 14.1. The ProcessInstanceLog, NodeInstanceLog and VariableInstanceLog classes enabled for processInstanceDS
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <persistence version="1.0" xsi:schemaLocation= "http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/persistence"> <persistence-unit name="org.jbpm.persistence.jpa"> <provider>org.hibernate.ejb.HibernatePersistence</provider> <jta-data-source>jdbc/processInstanceDS</jta-data-source> <class>org.drools.persistence.info.SessionInfo</class> <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class> <class>org.drools.persistence.info.WorkItemInfo</class> <class>org.jbpm.process.audit.ProcessInstanceLog</class> <class>org.jbpm.process.audit.NodeInstanceLog</class> <class>org.jbpm.process.audit.VariableInstanceLog</class> <properties> <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/> <property name="hibernate.max_fetch_depth" value="3"/> <property name="hibernate.hbm2ddl.auto" value="update"/> <property name="hibernate.show_sql" value="true"/> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.BTMTransactionManagerLookup"/> </properties> </persistence-unit> </persistence>
- Register a logger on your Kie Session.
Example 14.2. Import the Loggers
import org.jbpm.process.audit.AuditLogService; import org.jbpm.process.audit.AuditLoggerFactory; import org.jbpm.process.audit.AuditLoggerFactory.Type; import org.jbpm.process.audit.JPAAuditLogService; ...
Example 14.3. Registering a Logger to a Kie Session
@PersistenceUnit(unitName = PERSISTENCE_UNIT_NAME) private EntityManagerFactory emf; private AuditLogService auditLogService; @PostConstruct public void configure() { auditLogService = new JPAAuditLogService(emf); ((JPAAuditLogService) auditLogService).setPersistenceUnitName(PERSISTENCE_UNIT_NAME); if( emf == null ) { ((JPAAuditLogService) auditLogService).setPersistenceUnitName(PERSISTENCE_UNIT_NAME); } RuntimeEngine runtime = singletonManager.getRuntimeEngine(EmptyContext.get()); KieSession ksession = runtime.getKieSession(); AuditLoggerFactory.newInstance(Type.JPA, ksession, null); }
- Optionally, call the method
addFilter
on the logger to filter out irrelevant information. Only information accepted by all filters appears in the database. - Logger classes can be viewed in the Audit View:
<dependency> <groupId>org.jbpm</groupId> <artifactId>jbpm-audit</artifactId> <version>6.0.1.Final</version> </dependency>