Логирование

На этой странице описано логирование в OpenBPM Engine.

SLF4J

Большинство модулей OpenBPM Engine, включая процессный движок, используют SLF4J как фасад для логирования. Поэтому вывод логов можно направить в любой бэкенд логирования, например Logback или Log4j.

Готовая настройка логирования для общего процессного движка

Если OpenBPM Engine установлен на сервер приложений как общий (shared) процессный движок, логирование уже настроено.

В дистрибутиве для Apache Tomcat логирование настроено через мост slf4j-jdk14. Это значит, что OpenBPM Engine направляет весь свой вывод в Java Util Logging. SLF4J API и мост slf4j-jdk14 лежат в общем classpath, поэтому они доступны всем приложениям, развернутым на сервере.

Бэкенд логирования для встроенного движка

Если модули OpenBPM Engine подключены к приложению через Maven, транзитивно подтягивается только API SLF4J. Без бэкенда логи никуда не выводятся.

Ниже приведены два варианта настройки логирования. Подробнее о подключении бэкенда см. документацию SLF4J.

Пример с использованием Java Util Logging

Если особых требований к бэкенду логирования нет, проще всего направить логи в Java Util Logging. Для этого добавьте Maven-зависимость:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-jdk14</artifactId>
  <version>2.0.17</version>
</dependency>

Пример с использованием Logback

Для более тонкой настройки логирования рекомендуется Logback.

Добавьте зависимость Logback:

<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>1.5.32</version>
</dependency>

Добавьте файл logback.xml. Пример конфигурации:

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- по умолчанию энкодер имеет тип
         ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- openbpm engine -->
  <logger name="io.openbpm" level="info" />

  <!-- распространенные зависимости -->
  <logger name="org.apache.ibatis" level="info" />
  <logger name="javax.activation" level="info" />
  <logger name="org.springframework" level="info" />

  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>

</configuration>

Также убедитесь, что MyBatis использует SLF4J. Для этого добавьте в код конфигурации вызов:

LogFactory.useSlf4jLogging();

Контекст данных процесса

Чтобы записи лога содержали сведения о текущем контексте выполнения, движок помещает данные выполнения процесса в Mapped Diagnostic Context (MDC).

Данные процесса хранятся в MDC все время выполнения и удаляются после успешного выхода из контекста выполнения. Если при выполнении возникло исключение, данные остаются в MDC, пока вызывающий контекст, то есть исполнитель заданий (Job Executor) или внешняя команда, не запишет его в лог.

Ключи, под которыми свойства доступны в MDC, задаются в конфигурации процессного движка.

Чтобы выводить данные MDC, измените шаблон (pattern) в конфигурации логирования. Пример для Logback:

<configuration>
  ...

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} context:[%X] - %msg%n</pattern>
    </encoder>
  </appender>

  ...
</configuration>

С context:[%X] в шаблоне в каждую запись лога выводятся все значения, которые лежат в MDC в момент ее создания. Подробнее о доступе к MDC см. документацию вашего фреймворка логирования, например документацию Logback.

Категории логирования

Процессный движок

Процессный движок пишет логи в следующие категории:

Логер Описание

io.openbpm.bpm.application

Сведения о процессных приложениях, развернутых в движке

io.openbpm.bpm.container

Операции контейнера в движке

io.openbpm.bpm.engine.bpmn.behavior

Операции, связанные с активити BPMN

io.openbpm.bpm.engine.bpmn.parser

События при разборе моделей BPMN

io.openbpm.bpm.engine.cfg

Сведения об инициализации конфигурации процессного движка

io.openbpm.bpm.engine.cmd

Начало и конец всех команд, выполняемых движком

io.openbpm.bpm.engine.context

Контексты команд, в том числе атомарные операции и трассировки стека BPMN во время выполнения

Уровень лога для трассировок стека BPMN (по умолчанию DEBUG) можно переопределить, см. раздел Параметры уровня логирования.

io.openbpm.bpm.engine.core

Операции ядра движка, например выполнение атомарных операций

io.openbpm.bpm.engine.dmn

Исключения при вычислении решений

io.openbpm.bpm.dmn.feel

События при вычислении решений движком FEEL на основе JUEL

io.openbpm.bpm.dmn.feel.scala

События при вычислении решений движком Scala FEEL

org.camunda.feel.FeelEngine

События при вычислении выражений движком Scala FEEL

io.openbpm.bpm.engine.externaltask

Внешние задачи

io.openbpm.bpm.engine.identity

Сервис IdentityService, например сведения о блокировке пользователя

io.openbpm.bpm.engine.incident

Сведения об обработке инцидентов

io.openbpm.bpm.engine.jobexecutor

Операции исполнителя заданий, например получение заданий

io.openbpm.bpm.engine.metrics

Сведения о метриках движка

io.openbpm.bpm.engine.migration

Исключения при миграции экземпляров процессов

io.openbpm.bpm.engine.persistence

Идентификаторы всех сущностей, которые движок вставляет, удаляет или обновляет в базе данных

io.openbpm.bpm.engine.plugin.admin

Сведения об авторизации администраторов при подключенном плагине AdministratorAuthorizationPlugin

io.openbpm.bpm.engine.pvm

Операции Process Virtual Machine (PVM), например вход в активити и выход из него, создание и удаление областей видимости (scope)

io.openbpm.bpm.engine.rest.exception

Исключения, выброшенные в REST API

io.openbpm.bpm.engine.script

Сведения об обработке скриптов, например вычисление и компиляция

io.openbpm.bpm.engine.security

Исключения при хешировании паролей

io.openbpm.bpm.engine.test

Логер для тестов движка

io.openbpm.bpm.engine.tx

Сведения о транзакциях, например фиксация и откат

io.openbpm.bpm.engine.util

Операции служебных классов движка: разбор XML, чтение потоков, ошибки загрузки классов, разбор интервалов и длительностей и т. д.

io.openbpm.bpm.webapp

События веб-приложений OpenBPM Engine (Cockpit, Tasklist и Admin), например вход и выход пользователя, а также время проверки кэша

По умолчанию движок выводит записи с уровнями ERROR, WARNING и INFO. Для более подробного вывода, например при отладке, задайте уровень DEBUG или TRACE.

Вывод логеров может измениться в следующих версиях OpenBPM Engine.

В Tomcat логированием управляет java.util.logging через реализацию Tomcat JULI. Уровни DEBUG и TRACE в этом окружении называются FINE и FINEST.

Когда использовать логеры движка

Если повысить уровень некоторых логеров движка, можно получить больше сведений для анализа его поведения. Учтите, что на уровне DEBUG или TRACE некоторые логеры выводят очень много данных. Ниже перечислены типичные случаи, когда более подробное логирование движка действительно помогает.

Команды базы данных

Чтобы увидеть команды, которые движок отправляет в базу данных, обычно достаточно повысить уровень логеров io.openbpm.bpm.engine.persistence и io.openbpm.bpm.engine.impl.persistence.entity. На уровне DEBUG они выводят все SQL-запросы с параметрами. На уровне TRACE выводятся также результаты запросов. Если запрос возвращает много строк, лог будет большим.

Однако часть команд эти два логера не охватывают. Полный список логеров, которые показывают все команды к базе данных:

  • io.openbpm.bpm.engine.persistence

  • io.openbpm.bpm.engine.impl.persistence.entity

  • io.openbpm.bpm.engine.impl.history.event

  • io.openbpm.bpm.engine.impl.batch

  • io.openbpm.bpm.engine.impl.dmn.entity.repository

  • io.openbpm.bpm.engine.history

Пример лога сервера:

25-Nov-2019 15:15:57.870 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03006 Cache state after flush: [
  PERSISTENT GroupEntity[development]
]
25-Nov-2019 15:15:57.871 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03009 SQL operation: 'INSERT'; Entity: 'AuthorizationEntity[id=19ac0d96-0f8e-11ea-8b01-e4a7a094a9d6]'
25-Nov-2019 15:15:57.871 FINE [thread-1] o.a.i.l.j.BaseJdbcLogger.debug ==>  Preparing: insert into ACT_RU_AUTHORIZATION ( ID_, TYPE_, GROUP_ID_, USER_ID_, RESOURCE_TYPE_, RESOURCE_ID_, PERMS_, REV_ ) values ( ?, ?, ?, ?, ?, ?, ?, 1 )
25-Nov-2019 15:15:57.872 FINE [thread-1] o.a.i.l.j.BaseJdbcLogger.debug ==> Parameters: 19ac0d96-0f8e-11ea-8b01-e4a7a094a9d6(String), 1(Integer), development(String), null, 2(Integer), development(String), 2(Integer)
25-Nov-2019 15:17:17.075 FINE [thread-2] o.a.i.l.j.BaseJdbcLogger.debug ==>  Preparing: update ACT_ID_GROUP set REV_ = ?, NAME_ = ?, TYPE_ = ? where ID_ = ? and REV_ = ?
25-Nov-2019 15:17:17.076 FINE [thread-2] o.a.i.l.j.BaseJdbcLogger.debug ==> Parameters: 2(Integer), Dev-Department(String), DEV(String), development(String), 1(Integer)

Чтобы включить логирование для отдельной сущности базы данных, укажите пространство имен маппера MyBatis. Обычно это полное имя класса сущности, например:

  • io.openbpm.bpm.engine.impl.batch.BatchEntity

  • io.openbpm.bpm.engine.impl.persistence.entity.JobEntity

  • io.openbpm.bpm.engine.impl.persistence.entity.VariableInstanceEntity

Диагностика выполнения заданий

Чтобы разобраться в выполнении заданий, для начала переключите следующие логеры на уровень DEBUG:

  • io.openbpm.bpm.engine.impl.persistence.entity.JobEntity: сведения, касающиеся непосредственно выполнения заданий;

  • io.openbpm.bpm.engine.jobexecutor: другие сведения о выполнении заданий, например получение заданий и операции выполнения;

  • io.openbpm.bpm.engine.cmd: начало и конец команд, по ним видно, какая команда запустила выполнение задания.

Лог сервера будет выглядеть примерно так:

25-Nov-2019 15:45:27.613 INFO [main] o.c.c.l.BaseLogger.logInfo ENGINE-14014 Starting up the JobExecutor[io.openbpm.bpm.engine.impl.jobexecutor.RuntimeContainerJobExecutor].
25-Nov-2019 15:45:27.615 INFO [Thread-6] o.c.c.l.BaseLogger.logInfo ENGINE-14018 JobExecutor[io.openbpm.bpm.engine.impl.jobexecutor.RuntimeContainerJobExecutor] starting to acquire jobs
25-Nov-2019 15:45:27.619 FINE [Thread-6] o.c.c.l.BaseLogger.logDebug ENGINE-13005 Starting command -------------------- AcquireJobsCmd ----------------------
25-Nov-2019 15:45:27.620 FINE [Thread-6] o.c.c.l.BaseLogger.logDebug ENGINE-13009 opening new command context
25-Nov-2019 15:45:27.689 FINE [Thread-6] o.a.i.l.j.BaseJdbcLogger.debug ==>  Preparing: select RES.ID_, RES.REV_, RES.DUEDATE_, RES.PROCESS_INSTANCE_ID_, RES.EXCLUSIVE_ from ACT_RU_JOB RES where (RES.RETRIES_ > 0) and ( RES.DUEDATE_ is null or RES.DUEDATE_ <= ? ) and (RES.LOCK_OWNER_ is null or RES.LOCK_EXP_TIME_ < ?) and RES.SUSPENSION_STATE_ = 1 and (RES.DEPLOYMENT_ID_ is null ) and ( ( RES.EXCLUSIVE_ = 1 and not exists( select J2.ID_ from ACT_RU_JOB J2 where J2.PROCESS_INSTANCE_ID_ = RES.PROCESS_INSTANCE_ID_ -- from the same proc. inst. and (J2.EXCLUSIVE_ = 1) -- also exclusive and (J2.LOCK_OWNER_ is not null and J2.LOCK_EXP_TIME_ >= ?) -- in progress ) ) or RES.EXCLUSIVE_ = 0 ) LIMIT ? OFFSET ?
25-Nov-2019 15:45:27.692 FINE [Thread-6] o.a.i.l.j.BaseJdbcLogger.debug ==> Parameters: 2019-11-25 15:45:27.621(Timestamp), 2019-11-25 15:45:27.621(Timestamp), 2019-11-25 15:45:27.621(Timestamp), 3(Integer), 0(Integer)
25-Nov-2019 15:45:27.693 FINE [Thread-6] o.a.i.l.j.BaseJdbcLogger.debug <==      Total: 1
25-Nov-2019 15:45:27.695 FINE [Thread-6] o.c.c.l.BaseLogger.logDebug ENGINE-13011 closing existing command context
25-Nov-2019 15:45:27.699 FINE [Thread-6] o.a.i.l.j.BaseJdbcLogger.debug ==>  Preparing: update ACT_RU_JOB SET REV_ = ?, LOCK_EXP_TIME_ = ?, LOCK_OWNER_ = ?, DUEDATE_ = ?, PROCESS_INSTANCE_ID_ = ?, EXCLUSIVE_ = ? where ID_= ? and REV_ = ?
25-Nov-2019 15:45:27.703 FINE [Thread-6] o.a.i.l.j.BaseJdbcLogger.debug ==> Parameters: 90(Integer), 2019-11-25 15:50:27.695(Timestamp), 62eae13f-c636-4a21-a80e-c82fc028a959(String), 2019-11-25 00:01:00.0(Timestamp), null, true(Boolean), 9e1a4275-0c41-11ea-8035-e4a7a094a9d6(String), 89(Integer)
25-Nov-2019 15:45:27.706 FINE [Thread-6] o.c.c.l.BaseLogger.logDebug ENGINE-13006 Finishing command -------------------- AcquireJobsCmd ----------------------
Диагностика взаимных блокировок

При взаимных блокировках (deadlock) логи движка тоже помогают, если повысить уровень логеров команд и персистентности. Сначала определите, какие ресурсы попали во взаимную блокировку, а затем выясните, какие именно две транзакции блокируют друг друга:

  • io.openbpm.bpm.engine.persistence: логер персистентности выводит идентификаторы всех сущностей движка, по ним видно, какие ресурсы вызывают взаимную блокировку;

  • io.openbpm.bpm.engine.cmd: вывод команд помогает определить границы транзакций, участвующих во взаимной блокировке.

Если проблема связана с конкретной сущностью (например, VariableInstance), включите логирование и для нее (io.openbpm.bpm.engine.impl.persistence.entity.VariableInstanceEntity). Тогда в вывод попадут все записи по этой сущности и будут видны ее изменения.

Пример записей, которые появятся в логе сервера после повышения уровня этих логеров:

25-Nov-2019 16:00:50.675 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-13005 Starting command -------------------- RemoveExecutionVariablesCmd ----------------------
25-Nov-2019 16:00:50.676 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-13009 opening new command context
25-Nov-2019 16:00:50.718 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03006 Cache state after flush: [
  PERSISTENT VariableInstanceEntity[0ec1ab1d-0f8d-11ea-8b01-e4a7a094a9d6]
  PERSISTENT ProcessDefinitionEntity[invoice:2:ae69d3b4-0c41-11ea-a8eb-e4a7a094a9d6]
  PERSISTENT HistoricVariableUpdateEventEntity[5eba854e-0f94-11ea-92d9-e4a7a094a9d6]
  PERSISTENT ExecutionEntity[0ec04b8b-0f8d-11ea-8b01-e4a7a094a9d6]
  PERSISTENT UserOperationLogEntryEventEntity[5ebb6faf-0f94-11ea-92d9-e4a7a094a9d6]
  PERSISTENT HistoricVariableInstanceEntity[ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6]
]
25-Nov-2019 16:00:50.722 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03008 Flush Summary: [
  INSERT UserOperationLogEntryEventEntity[5ebb6faf-0f94-11ea-92d9-e4a7a094a9d6]
  INSERT HistoricVariableUpdateEventEntity[5eba854e-0f94-11ea-92d9-e4a7a094a9d6]
  DELETE VariableInstanceEntity[ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6]
  UPDATE HistoricVariableInstanceEntity[ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6]
]
25-Nov-2019 16:00:50.725 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03009 SQL operation: 'INSERT'; Entity: 'HistoricVariableUpdateEventEntity[id=5eba854e-0f94-11ea-92d9-e4a7a094a9d6]'
25-Nov-2019 16:00:50.726 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03009 SQL operation: 'DELETE'; Entity: 'VariableInstanceEntity[id=ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6]'
25-Nov-2019 16:00:50.727 FINE [thread-1] o.a.i.l.j.BaseJdbcLogger.debug ==>  Preparing: delete from ACT_RU_VARIABLE where ID_ = ? and REV_ = ?
25-Nov-2019 16:00:50.728 FINE [thread-1] o.a.i.l.j.BaseJdbcLogger.debug ==> Parameters: ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6(String), 2(Integer)
25-Nov-2019 16:00:50.730 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-03009 SQL operation: 'UPDATE'; Entity: 'HistoricVariableInstanceEntity[id=ddea4bef-0f93-11ea-b2ca-e4a7a094a9d6]'
25-Nov-2019 16:00:50.737 FINE [thread-1] o.c.c.l.BaseLogger.logDebug ENGINE-13006 Finishing command -------------------- RemoveExecutionVariablesCmd ----------------------

Во фрагменте видны начало и конец команды RemoveExecutionVariablesCmd, сводка flush (Flush Summary) и команды базы данных для экземпляра переменной.

Устаревшее: Java Util Logging

Некоторые модули OpenBPM Engine все еще используют Java Util Logging напрямую. Это считается устаревшим, в следующих версиях эти модули постепенно перейдут на SLF4J.

Модули, которые все еще используют Java Util Logging:

  • openbpm-engine-ejb-service

  • openbpm-engine-jobexecutor-ra

  • openbpm-engine-jobexecutor-rar

  • openbpm-engine-cdi

  • openbpm-engine-spring

  • openbpm-engine-rest

Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.