Chapter 17. 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 17.1. Fields of the ProcessInstanceLog table

FieldDescriptionNullable

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 17.2. Fields of the NodeInstanceLog table

FieldDescriptionNullable

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 17.3. Fields of the VariableInstanceLog table

FieldDescriptionNullable

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 necessary, define your own data model of custom information and use the process event listeners to extract the information.

17.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:

  1. 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 17.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>

  2. Register a logger on your Kie Session.

    Example 17.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 17.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);

  }
  3. Optionally, call the method addFilter on the logger to filter out irrelevant information. Only information accepted by all filters appears in the database.

  4. 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>