15.4. Managing log files

Red Hat JBoss BPM Suite manages most of the required maintenance. Automatically cleaned runtime data includes:
  • Process instances data, which is removed upon process instance completion.
  • Work items data, which is removed upon work item completion.
  • Task instances data, which is removed upon completion of a process to which given task belongs.
Runtime data, which may not be automatically cleaned, includes session information data. This depends on the selected runtime strategy:
  • Singleton strategy ensures that session information runtime data will not be automatically removed.
  • Per request strategy allows automatic removal when a given request terminates.
  • Per process instances will be automatically removed when process instance mapped to a given session completes or is aborted.
Red Hat JBoss BPM Suite does not remove executor request and error information.
In order not to lose track of process instances, Red Hat JBoss BPM Suite offers audit data tables. These are used by default and keep track of the BPM Suite environment. JBoss BPM Suite offers two ways of how to manage and maintain the audit data tables:
  • Automatic clean-up
  • Manual clean-up

15.4.1. Automatic Clean-Up

Automatic clean-up uses the LogCleanupCommand executor command, which consists of logic to clean up all or selected data automatically. An advantage of the automatic clean-up method is the ability to schedule repeated clean-ups by using reoccurring job feature of the JBoss BPM Suite executor. This means that when one job completes, it provides information to the JBoss BPM Suite executor if and when the next instance of this job should be executed. By default, LogCleanupCommand is executed once a day but can be reconfigured to run on different intervals.
There are several important configuration options that can be used with the LogCleanupCommand command:

Table 15.4. LogCleanupCommand parameters table

Name
Description
Is Exclusive
SkipProcessLog
Indicates if the clean-up of process instances, node instances and variables log cleanup should be omitted (default: false)
No, can be used with other parameters
SkipTaskLog
Indicates if the task audit and the task event log clean-up should be omitted (default: false)
No, can be used with other parameters
SkipExecutorLog
Indicates if the JBoss BPM Suite executor entries clean-up should be omitted (default: false)
No, can be used with other parameters
SingleRun
Indicates if the job routine should run only once (default: false)
No, can be used with other parameters
NextRun
Sets a date for the next run. For example, 12h is set for jobs to be executed every 12 hours. If the option is not given, the next job will run 24 hours after the completion of the current job
Yes, cannot be used when the OlderThanPeriod parameter is used
OlderThan
Causes logs older than the given date to be removed. The date format is YYYY-MM-DD. Usually, this parameter is used for single run jobs
Yes, cannot be used when the NextRun parameter is used
OlderThanPeriod
Causes logs older than the given timer expression should be removed. For example, set 30d to remove logs older than 30 day from current time
No, can be used with other parameters
ForProcess
Specifies process definition ID for which logs should be removed
No, can be used with other parameters
ForDeployment
Specifies deployment ID for which logs should be removed
No, can be used with other parameters
EmfName
Persistence unit name that shall be used to perform operation deletion
N/A

Note

LogCleanupCommand does not remove any active instances, such as running process instances, task instances, or executor jobs.

Warning

While all audit tables have a time stamp, some may be missing other parameters, such as process id, or deployment id. For that reason, it is recommended to use the date parameter when managing the clean-up job routine.

15.4.2. Setting up Automatic Clean-up Job

To set up automatic clean-up job, do the following:
  1. Open Business Central in your web browser (if running locally http://localhost:8080/business-central) and log in as a user with the admin role.
  2. Go to Deploy → Jobs.
  3. Click on next to Action and select New Job.
  4. Enter a name, due date and time. Enter the following into the Type text field: 
    org.jbpm.executor.commands.LogCleanupCommand
  5. Click on Add Parameter if you wish to use parameters listed above. In the key section, enter a parameter name. In the value section, enter true or false, depending on the desired outcome.
  6. Click Create to finalize the job creation wizard. You have successfully created an automatic clean-up job.

15.4.3. Manual Clean-Up

You may make use of audit API to do the clean-up manually with more control over parameters and thus more control over what will be removed. Audit API is divided into following areas:
  • Process audit, which is used to clean up process, node and variables logs, accessible in the jbpm-audit module
  • Task audit, which is used to clean up tasks and task events, accessible in the jbpm-human-task-audit module
  • Executor jobs, which is used to clean up executor jobs and errors, accessible in the jbpm-executor module
Modules are sorted hierarchically and can be accessed as follows: 
  • org.jbpm.process.audit.JPAAuditLogService
  • org.jbpm.services.task.audit.service.TaskJPAAuditService
  • org.jbpm.executor.impl.jpa.ExecutorJPAAuditService
Several examples of manual clean-up follow:

Example 15.4. Removal of completed process instance logs

import org.jbpm.process.audit.JPAAuditLogService;
import org.kie.internal.runtime.manager.audit.query.ProcessInstanceLogDeleteBuilder;
import org.kie.api.runtime.process.ProcessInstance;

JPAAuditLogService auditService = new JPAAuditLogService(emf);
ProcessInstanceLogDeleteBuilder updateBuilder = auditService.processInstanceLogDelete().status(ProcessInstance.STATE_COMPLETED);
int result = updateBuilder.build().execute();

Example 15.5. Task audit logs removal for the org.jbpm:HR:1.0 deployment

import org.jbpm.services.task.audit.service.TaskJPAAuditService;
import org.kie.internal.task.query.AuditTaskDeleteBuilder;

TaskJPAAuditService auditService = new TaskJPAAuditService(emf);
AuditTaskDeleteBuilder updateBuilder = auditService.auditTaskDelete().deploymentId("org.jbpm:HR:1.0");
int result = updateBuilder.build().execute();

Example 15.6. Executor error and requests removal

import org.jbpm.executor.impl.jpa.ExecutorJPAAuditService;
import org.kie.internal.runtime.manager.audit.query.ErrorInfoDeleteBuilder;
import org.kie.internal.runtime.manager.audit.query.RequestInfoLogDeleteBuilder;

ExecutorJPAAuditService auditService = new ExecutorJPAAuditService(emf);
ErrorInfoDeleteBuilder updateBuilder = auditService.errorInfoLogDeleteBuilder().dateRangeEnd(new Date());
int result = updateBuilder.build().execute();

RequestInfoLogDeleteBuilder updateBuilder2 = auditService.requestInfoLogDeleteBuilder().dateRangeEnd(new Date());
result = updateBuilder.build().execute();

Note

When removing executor entries, ensure that the error information is removed before the request information because of constraints setup on database.

Warning

Parts of the code utilize internal API. While this does not have any direct impact on the functionality of our product, internal API is subject to change and Red Hat cannot guarantee backward compatibility.