Руководство по системному администрированию#

Сценарии администрирования#

Для выполнения сценариев администрирования не требуется какая-либо роль согласно ролевой модели Компонента.

При deploy в системе контейнеризации все токены, пароли, сертификаты и иная чувствительная информация хранится в одном из типов хранилищ:

• в секретах системы управления контейнерами;

• в файловой системе pod. Все токены, пароли, сертификаты и иная чувствительная информация получена из внешней системы хранения секретов Secret Management System.

Стратегия снятия резервных копий зависит от критичности данных, подлежащих сохранению, и определяется группой сопровождения.

Компонент Engine (BPMX) продукта Platform V Flow (BPM) (далее по тексту – BPMX) состоит из следующих модулей:

• bpmx-engine;

• bpmx-gateway;

• bpmx-scheduler.

Для каждого из модулей есть файл application.yml, который содержит блоки для настроек. Основные настройки для сервисов:

bpmx-engine

• блок persistence – настройки подключения к Kafka для хранения информации при обработке процессов (рекомендуемые параметры настройки);

• блок engine – настройки для исполнения процессов;

• блок management – настройки Spring actuator для получения метрик;

• блок spring – настройки spring-приложения;

• блок htm – настройки интеграции с компонентом UTSK;

• блок grafana-config – настройки подключения к grafana;

• блок available-zones – настройки зон работы приложения.

bpmx-gateway

• блок auth — настройки аутентификации пользователя (рекомендуемые режимы и настройки описаны в документации компонента BPM User Plane продукта Platform V Flow);

• блок persistence – настройки подключения к Kafka для хранения информации при обработке процессов (рекомендуемые параметры настройки);

• блок hikari - настройки подключения к БД;

• блок zookeeper - настройки подключения к Zookeeper;

• блок engine – настройки для исполнения процессов;

• блок management – настройки Spring actuator для формирования метрик мониторинга;

• блок api – настройки для подключения к API;

• блок spring – настройки spring-приложения;

• блок tracing – настройки для подключения к сервису tracing;

• блок audit – настройки для подключения к сервису аудита (рекомендуемые параметры настройки «Интеграция с компонентом Аудит (AUDT) Platform V Audit SE (AUD)»;

• блок datasource – настройки для подключения к БД.

• блок gateway - дополнительные настройки по работе сервиса.

bpmx-scheduler

• блок persistence – настройки подключения к Kafka для хранения информации при обработке процессов (рекомендуемые параметры настройки);

• блок management – настройки Spring actuator, необходимые для формирования метрик мониторинга;

• блок spring – настройки spring-приложения.

К сценариям администрирования относятся все действия и настройки, указанные в этом разделе, а также просмотр журналов (logs) и метрик мониторинга.

Сценарий «Загрузка моделей процессов»#

Фабрики (потребители), работающие с компонентом BPMX, должны самостоятельно загружать (разворачивать) модели в BPMX.

Установка модели в среду исполнения реализуется с помощью Rest API. Для этого необходимо использовать метод:

POST /deployments

При параллельной установке версий 4.x и 5.x:

• api для установки в версию 4.х: POST {хост}/user/v4/deployments/upload;

• api для установки в версию 5.х: POST {хост}/system/v5/deployments.

API в формате OpenAPI представлены в Справочнике API.

Сценарий «Управление конфигурацией»#

Настройка для хранения данных при исполнении процессов#

В BPMX для хранения данных при исполнении экземпляров процессов используется Kafka. Информация хранится в следующих topics Kafka:

• bpmx-async-start – Job для запуска экземпляров процессов;

• bpmx-retry-policy – информация о политиках повтора;

• bpmx-processes – информация о процессах: атрибуты, xml-модели, изображения схем процессов;

• bpmx-async-jobs – информация о Job для исполнения;

• bpmx-processinstance-context – информация о контексте исполнения экземпляров процессов;

• bpmx-scheduled-jobs – информация о таймерах/автоматических повторах шагов;

• bpmx-eventsubscriptions – подписки экземпляров процессов на сообщения/сигналы.

При исполнении экземпляров процессов сервисы BPMX получают и записывают информацию в соответствующем topic.

Для сервисов BPMX (bpmx-engine,bpmx-gateway,bpmx-scheduler) в файле application.yml задаются настройки подключения к Kafka в блоке persistence:

• persistence

  • kafka

    • client-id – идентификатор клиента;

    • bootstrap-servers – список серверов Kafka-кластера;

    • ssl

      • key-password – пароль от приватного ключа;

      • key-store-location – путь к хранилищу сертификатов для Kafka;

      • key-store-password – пароль от хранилища сертификатов;

      • key-store-type – тип хранилища сертификатов;

      • trust-store-location – путь к хранилищу доверенных сертификатов для Kafka;

      • trust-store-password – пароль от хранилища доверенных сертификатов;

      • trust-store-type – тип хранилища доверенных сертификатов;

      • protocol – протокол безопасности (TLSv1.2, TLSv1.3);

      • security

        • protocol – протокол безопасности для соединения с Kafka-брокером;

      • listener

        • concurency – количество потоков;

      • producer

        • properties

          • max.request.size – максимальное количество байтов в запросе;

          • max.block.ms – время для аллокации сообщения в буфере (включая время для получения метаданных от брокера);

          • delivery.timeout.ms – суммарное время ожидания отправки сообщения (включая время хранения сообщения в буфере, время подтверждения доставки от брокера);

          • request.timeout.ms – время ожидания ответа на запрос от брокера;

          • linger.ms– время задержки перед отправкой сообщений из буфера в topics Kafka;

      • consumer

        • groupId – указывает имя группы потребителей, к которой принадлежит потребитель Kafka;

        • auto-offset-reset – указывает, что делать, если в Kafka нет начального offset или если текущий offset больше не существует на сервере;

        • properties

          • max.poll.interval.ms – максимально возможный интервал времени между запросами к серверу;

          • session.timeout.ms – время жизни (TTL) сессии.

Также в блоке persistence доступны дополнительные настройки для topics Kafka:

• name – название topic;

• concurrency – количество потоков-обработчиков topic;

• partitions – количество партиций topic;

• replicationFactor – это количество копий данных через несколько брокеров;

• consumer – настройки consumer topic (можно переопределить те, что уже заданы)

  • autoOffsetReset – определяет, как consumer должен вести себя при потреблении из партиции topic, когда нет начального offset;

• producer – настройки producer topic (можно переопределить те, что уже заданы)

  • compressionType – тип сжатия данных topic;

• topicConfig

  • cleanup.policy: – политика очистки topic;

  • min.cleanable.dirty.ratio – параметр определяет, как часто будет очищаться журнал (с записями из topic);

  • min.insync.replicas – данные считаются закомиченными, когда они записываются во все синхронизированные реплики. Их количество настраивается в данном параметре.

Настройки для topics:

  asyncJobsTopic:
    name: bpmx-asyncjobs
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    consumer:
      auto-offset-reset: latest
      properties:
        max.poll.interval.ms: 300000
        session.timeout.ms: 45000
    producer:
      compressionType: snappy
      properties:
        max.request.size: 1048576
        max.block.ms: 60000
        delivery.timeout.ms: 120000
        request.timeout.ms: 30000
        linger.ms: 0
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  asyncStartsTopic:
    name: bpmx-asyncstart
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  contextTopic:
    name: bpmx-instancecontexts
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    consumer:
      autoOffsetReset: earliest
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  eventSubscriptionsTopic:
    name: bpmx-eventsubscriptions
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    consumer:
      autoOffsetReset: earliest
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  scheduledJobsTopic:
    name: bpmx-scheduledjobs
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  processDefinitionTopic:
    name: bpmx-process
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1
  retryPolicyTopic:
    name: bpmx-retrypolicy
    concurrency: 1
    partitions: 1
    replicationFactor: 1
    topicConfig:
      cleanup.policy: compact
      min.cleanable.dirty.ratio: 0.5
      min.insync.replicas: 1

Важно! В настройках topics 'contextTopic', 'eventSubscriptionsTopic', 'scheduledJobsTopic', 'processDefinitionTopic', 'retryPolicyTopic' значение параметра 'cleanup.policy' обязательно должно быть равно 'compact'. В случае автоматического создания topics Kafka значения также установятся автоматически (не рекомендуется). Если topics Kafka создаются вручную, то параметр требуется указать самостоятельно.

Рекомендация по выбору количества партиций#

Компонент BPMX масштабируется по горизонтали с помощью добавления узлов кластера (pods). Однако масштабирование ограничено количеством партиций, изначально сконфигурированных для кластера, поскольку работа внутри одной партиции не может быть параллельной.

Следовательно, необходимо заранее определить достаточное количество партиций (с учетом потенциального масштабирования), так как их количество не может быть изменено после завершения подготовки кластера. Кроме того, рекомендуется выделять количество партиций для topics, кратное количеству pod. В этом случае нагрузка на узлы (pods) будет распределена наиболее оптимально.

Рекомендация по настройке кафки для функционала Kafka Throw Events#

Для корректной работы функционала Kafka Throw Events добавлена валидация при запуске модуля на значения настроек. Значение engine.messages.kafka.consumer.properties.max.poll.interval.ms должно быть больше, чем engine.messages.kafka.consumer.properties.max.poll.records * engine.persistence.kafka.producer.properties.linger.ms. При несоблюдении данного правила модуль не запустится.

Рекомендация по настройке размера сообщений в Kafka#

При работе с сообщениями, превышающими 1 Мб, требуется настройка лимитов на нескольких уровнях взаимодействия с топиком. Для продьюсера топика увеличивается значение свойства max.request.size, для консьюмера - fetch.max.bytes. В конфигурации топика устанавливается свойство message.max.bytes, которое используется при автоматическом создании топика и не изменяется в последующем.

Блок настроек BPMX#

Настройка асинхронного взаимодействия с компонентом TaskList (UTSK) продукта Platform V Flow (BPM)#

По умолчанию используется синхронное взаимодействие с компонентом UTSK. Существует возможность включить асинхронное взаимодействие в части API по операциям над пользовательскими задачами.

Для транспорта от BPMX к UTSK:

• create – создание user task

• abort – прерывание user task

Для транспорта от UTSK к BPMX:

• complete – завершение user task

• abort – прерывание user task

При создании задачи в асинхронном режиме со стороны BPMX отсутствует передача callback url инфо для операций complete, abort (abortCallback, completeCallback поля DTO соответственно). По этой причине переключение с асинхронного режима взаимодействия (kafka) на синхронный (HTTP) невозможно в штатном режиме.

Настройки работы асинхронного взаимодействия для указанных выше операций осуществляются через файл application.yml, блок engine.htm.async. Настройки присутствуют в сервисах bpmx-engine, bpmx-gateway.

Общие настройки асинхронного взаимодействия:

• enabled – включение или выключение асинхронного взаимодействия с компонентом UTSK;

• format – формат событий, доступны варианты "cloud-events-spec" или "none";

• userTaskOutboundEventsTopic – topic исходящих событий в UTSK;

• userTaskInboundEventsTopic – topic входящих событий от UTSK;

• acceptedModuleIds – дополнительные модули, сообщения от которых будут приниматься (фильтрация работает при наличии параметра).

Блок kafka, настройки подключения к Kafka серверу:

engine:
  htm:
    async:
      enabled: false
      format: cloud-events-spec
      userTaskOutboundEventsTopic: toHtmUserTaskEvents
      userTaskInboundEventsTopic: fromHtmUserTaskEvents
      acceptedModuleIds: htm-app
      kafka:

Настройка отправки событий истории исполнения процесса#

Публикация событий может осуществляться по следующим каналам:

• брокер сообщений Kafka;

Подробнее о публикуемых событиях в документе Руководство разработчика, «Публикация истории». Настройки для отправки событий присутствуют в сервисе bpmx-engine, в блоке engine.events

Настройки отправки событий в Kafka:

• enableProcessModelEvents – включение/отключение отправки событий по моделям процессов;

• enableProcessInstanceEvents – включение/отключение отправки событий по экземплярам процессов;

• format – формат событий (none, cloud-events-spec, synapse-eda-spec);

• processInstanceUpdateEventTopic – имя topic для событий обновления экземпляра процесса;

• processModelUpdateEventTopic – имя topic для событий изменения модели;

• source – источник события (в формате URI);

• kafka.producer – параметры подключения к kafka брокеру:

  • bootstrap-servers – список node kafka кластера (пример: localhost:9093,localhost:9193);

  • client-id – идентификатор клиента, нужен для логирования на стороне брокера;

  • retries – количество повторных попыток отправки сообщения в случае ошибки;

  • buffer-memory – размер буфера отправки сообщений (байт);

  • batch-size – размер пакета сообщений (байт);

  • compression-type – тип сжатия (none, gzip, snappy, lz4, zstd);

  • acks – необходимое количество подтверждений для успешной записи;

  • ssl:

    • key-password – пароль от приватного ключа;

    • key-store-location – путь к хранилищу ключей;

    • key-store-password – пароль от хранилища;

    • key-store-type – тип хранилища (JKS, PKCS12, PEM);

    • trust-store-location – путь к доверенному хранилищу ключей;

    • trust-store-password – пароль от хранилища;

    • trust-store-type – тип хранилища (JKS, PKCS12, PEM);

    • protocol – протокол безопасности (TLSv1.2, TLSv1.3).

  • security:

    • protocol – протокол взаимодействия с брокером (PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL).

  • properties:

    • max.block.ms – время для аллокации сообщения в буфере (включая время для получения метаданных от брокера);

    • delivery.timeout.ms – суммарное время ожидания отправки сообщения, включая время хранения сообщения в буфере, время подтверждения доставки от брокера (должен быть не менее суммы параметров request.timeout.ms и linger.ms);

    • request.timeout.ms – время ожидания ответа на запрос от брокера;

    • linger.ms – время задержки перед отправкой сообщений из буфера в topics.

engine:
  events:
    enableProcessModelEvents: false
    enableProcessInstanceEvents: false
    format: none
    processInstanceUpdateEventTopic: process-instance-update-event
    processModelUpdateEventTopic: process-model-update-event
    source: bpms
    kafka:
      producer:
        bootstrap-servers: host1:9093, host2:9093
        client-id: bpms
        retries: 0
        buffer-memory: 1m
        batch-size: 16384
        compression-type: none
        acks: 1
        ssl:
          key-password: secret
          key-store-location: /path/to/key-store.jks
          key-store-password: secret
          key-store-type: JKS
          trust-store-location: /path/to/trusted-store.jks
          trust-store-password: secret
          trust-store-type: JKS
          protocol: TLSv1.2
        security:
          protocol: SSL
        properties:
          max.block.ms: 1000
          delivery.timeout.ms: 10000
          request.timeout.ms: 5000
          linger.ms: 1000

Далее будут описаны схемы событий, которые не меняются в зависимости от канала отправки сообщения.

Схема события при установке архива моделей процессов

Схема события для экземпляров процессов

Информация, доступная о контексте процесса:

• GlobalInstanceID – ID процесса (в формате UUID), который пользователи могут передавать со стартовым сообщением. Если GlobalInstanceID не задан явно, то он генерируется произвольно, также в формате UUID (BusinessKey не выводится в Контекст процесса, но фактически имеет то же значение, что и GlobalInstanceID);

• FLOW_PID – служебное поле контекста (processInstanceID – идентификатор экземпляра процесса).

Настройки для отправки/получения сообщений по событиям в процессах#

Для поддержки исполнения событий-сообщений (catch-принимающих и throw-отправляющих) реализовано взаимодействие с брокером сообщений Kafka.

Описание и сценарии использования доступны в Руководстве разработчика, «Отправка/получение сообщений по событиям в процессах».

Данные настройки присутствуют в сервисах bpmx-engine, bpmx-gateway в блоке engine.messages.

В блоке engine.messages задаются следующие настройки для отправки/получения сообщений:

• enabled – включение/отключение функционала взаимодействия с Kafka для отправки/получения сообщений по событиям (false*/true**);

• format – формат конверта для отправляемых/получаемых сообщений. Возможные значения: cloud-events-spec**, synapse-eda-speс**, none*;

• retry: параметры повторных запросов, если потребитель присылает сообщение раньше, чем активен соответствующий шаг;

  • back-off-period – период между повторными запросами (200 ms*);

  • max-attempts – количество попыток повторных запросов (15*);

• source – источник событий для сообщений в Kafka (bpms*);

• kafka:

  • client-id – идентификатор клиента;

  • bootstrap-servers – список серверов Kafka-кластера (пример: localhost:9093,localhost:9193);

• ssl:

  • key-password: пароль от приватного ключа;

  • key-store-location – путь к хранилищу сертификатов для Kafka (file:///home/jboss/messages/keystore.jks);

  • key-store-password – пароль от хранилища сертификатов;

  • key-store-type – тип хранилища сертификатов (JKS*);

  • trust-store-location – путь к хранилищу доверенных сертификатов для Kafka;

  • trust-store-password – пароль от хранилища доверенных сертификатов;

  • trust-store-type – тип хранилища доверенных сертификатов;

  • protocol – протокол безопасности (TLSv1.2*, TLSv1.3**);

• security:

  • protocol – протокол безопасности для соединения с Kafka-брокером (SSL*);

• producer:

  • properties:

    • max.request.size: максимальное количество байтов в запросе (1048576*);

    • max.block.ms: время для аллокации сообщения в буфере (включая время для получения метаданных от брокера) (1000 ms*, 30000 ms**);

    • delivery.timeout.ms: суммарное время ожидания отправки сообщения (включая время хранения сообщения в буфере, время подтверждения доставки от брокера) (10000 ms*, 120000 ms**);

    • request.timeout.ms: время ожидания ответа на запрос от брокера (5000 ms*, 30000 ms**);

    • linger.ms: время задержки перед отправкой сообщений из буфера в topics Kafka (1000 ms*, 0 ms**);

• consumer:

  • properties:

    • max.poll.interval.ms: максимально возможный интервал времени между запросами к серверу (300000 ms*);

    • session.timeout.ms: время жизни (TTL) сессии (45000 ms*);

    • max.poll.records : максимальное количество записей для обработки за один вызов (500 *);

Для коректной работы важно чтобы значение engine.messages.kafka.consumer.properties.max.poll.interval.ms было больше чем engine.messages.kafka.consumer.properties.max.poll.records * engine.persistence.kafka.producer.properties.linger.ms

* – рекомендованное значение/значение по умолчанию;

** – возможное значение.

Описание генерации блока engine.messages.events приведено в Руководстве по установке, «Настройки для отправки/получения сообщений по событиям в процессах».

Пример блока с настройками:

engine:
  messages:
    enabled: false
    format: none
    retry:
      back-off-period: 200
      max-attempts: 3
    source: bpms
    kafka:
      client-id: bpms
      bootstrap-servers: server1:9093, server2:9093
    ssl:
      key-password: secret
      key-store-location: /path/to/key-store.jks
      key-store-password: secret
      key-store-type: JKS
      trust-store-location: /path/to/trusted-store.jks
      trust-store-password: secret
      trust-store-type: JKS
      protocol: TLSv1.2
  security:
    protocol: PLAINTEXT
  producer:
    properties:
      max.request.size: 1048576
      max.block.ms: 1000
      delivery.timeout.ms: 10000
      request.timeout.ms: 5000
      linger.ms: 1000
  consumer:
    properties:
      max.poll.interval.ms: 300000
      session.timeout.ms: 45000
      max.poll.records: 500

Для принимающих событий в конфигурации обязательно добавлять настройки topics Kafka и consumer group.

Для отправляющих событий настройка topic Kafka является опциональной, по умолчанию название сообщения является topic Kafka. Эти настройки добавляются в блок engine.messages.events.

Возможные форматы сообщений, отправляемых в Kafka:

• cloud-events;

• synapse.

Подробнее примеры отправляемых сообщений в конверте CloudEvent и Synapse описаны в Руководстве прикладного разработчика, раздел «Сценарии использования».

Пример блока с настройками:

engine: 
  messages:
    events:
      firstProcessId: // Идентификатор модели процесса
        firstMessage: // Имя сообщения
          topic: testMessageTopic // Имя очереди
          consumerGroup: testConsummerGroup // вводится при необходимости
          concurrency: 1 //значение по умолчанию, вводится при необходимости
        secondMessage:
          topic: testMessageTopic // Второе имя сообщения
          consumerGroup: testConsummerGroup // вводится при необходимости
      secondProcessId: // Идентификатор модели процесса (при необходимости)
        firstMessage: // Имя сообщения (при необходимости)
          topic: testMessageTopic // Имя очереди (при необходимости)
          consumerGroup: testConsummerGroup // вводится при необходимости

Для генерации блока engine.messages.events добавлена переменная:

bpmx.sberflow-engine.ose.configmap.application.engine.messages.events.processes_map

Пример заполнения переменной:

• Процессы разделяются по ";"

• ID процесса и его сообщения по "!" (так как количество сообщений - произвольное)

• Сообщения одного процесса разделяются по "&"

• Параметры сообщения (имя, топик, группа консьюммера, concurrency) - разделяются по ":"

firstProcessId!firstMessage:testMessageTopic1:testConsummerGroup1:1;
secondProcessId!firstMessage:testMessageTopic2:testConsummerGroup2&secondMessage:testMessageTopic3:testConsummerGroup3"

Необходимо обязательно указывать в настройках ID процесса и название сообщения, для которых задаются настройки

Для корректной работы функционала (защиты от дублей) необходимо совместное использование идемпотентного старта (см. Раздел "Настройки идемпотентного старта")

Настройка белых списков разрешенных классов/методов в скриптах внутри моделей процессов#

Данные настройки присутствуют в сервисе bpmx-engine в блоке engine.scriptengine.

В файле конфигурации application.yml в блоке engine.scriptengine должны быть настроены следующие переменные:

• engine.scriptengine.enableScriptSandbox – включение исполнения скриптов через исполнения скриптов sberflow-script-sandbox;

• engine.scriptengine.enableSecurityScriptTask – включение безопасного исполнения скриптов;

• engine.scriptengine.whitelistPaths – путь к файлу, содержащему перечень методов/классов, которые могут использоваться в действиях типа Выполнение сценария.

engine:
  scriptengine:
    enableScriptSandbox: true
    enableSecurityScriptTask: true
    whitelistPaths: 
      - "classpath:whitelists/generic-whitelist"

При использовании безопасного исполнения скриптов:

• для скриптов на Groovy применяются ограничения на использование методов/функций согласно разрешенному белому списку (все, что не указано в whitelist запрещено для использования);

• запрещены методы/классы, указанные ниже (даже при добавлении соответствующих сигнатур в whitelist данные методы/классы нельзя будет исполнить):

  • "method java.lang.Runtime exit int";

  • "method java.lang.Runtime halt int";

  • "staticMethod java.lang.System exit int";

  • "new org.kohsuke.groovy.sandbox.impl.Checker$SuperConstructorWrapper java.lang.Object[]";

  • "new org.kohsuke.groovy.sandbox.impl.Checker$ThisConstructorWrapper java.lang.Object[]".

  • для скриптов на JavaScript будет недоступен вызов Java при исполнении.

Примеры содержимого файла whitelist#

Конструкторы (с параметром и без):

new java.util.ArrayList java.util.Collection  
new groovy.json.JsonBuilder 

Статические методы (с параметром и без):

staticMethod java.util.Arrays asList java.lang.Object[]  
staticMethod java.util.Arrays toString java.lang.Object[]  
staticMethod java.util.Base64 getDecoder  
staticMethod java.util.Base64 getEncoder

Методы (с параметром и без):

method java.lang.Object equals java.lang.Object
method java.io.Reader read

Статическое поле:

staticField java.lang.Integer MAX_VALUE

Если в методе или конструкторе более одного параметра, тогда их типы перечисляются через пробел:

method java.io.Reader read char[] int int
new java.lang.Enum java.lang.String int

Настройка ограничения исполнения пользовательских скриптов#

Ограничение времени исполнения пользовательских скриптов производится в блоке engine.scriptengine:

• engine.scriptengine.executeInSeparateThread – включение исполнения скрипт-таски в отдельном потоке. По умолчанию: false;

• engine.scriptengine.timeout – тайм-аут исполнения скрипта-таски, после которого произойдет ее прерывание (выполнится только в случае, если engine.scriptengine.executeInSeparateThread=true). По умолчанию 10000.

engine:
  scriptengine:
    executeInSeparateThread: false
    timeout: 10000

Настройки персистирования#

Точки персистирования – это точки сохранения информации для внутреннего использования BPMX (сохраняется текущее состояние процесса (execution)).

Список возможных точек персистирования:

• START_EVENT(StartEvent);

• END_EVENT(EndEvent);

• SERVICE_TASK(ServiceTask);

• SCRIPT_TASK(ScriptTask);

• USER_TASK(UserTask);

• CATCH_EVENT(IntermediateCatchEvent) – промежуточное событие-перехватчик (шаг процесса для которого необходим определенный триггер);

• RECEIVE_TASK(ReceiveTask);

• DEACTIVATE(Deactivate) – выключение точек персистирования.

Настройки персистирования в BPMX присутствуют в сервисе bpmx-engine в блоке engine:

• persistPoints – перечисление точек персистирования для шагов бизнес-процессов (для отключения необходимо указать Deactivate).

Пример:

persistPoints: 'StartEvent,UserTask,IntermediateCatchEvent,ReceiveTask,ServiceTask'

Выполнение конкретного экземпляра процесса не может быть приостановлено на шагах с типом:

• scriptTask;

• gateway;

• manualTask;

Настройка времени нахождения экземпляра процесса в статусе "Инцидент"#

Если в процессе выполнения шага процесса после срабатывания политик повтора (если таковые были настроены) в экземпляре процесса произошла ошибка, то он переходит в статус Инцидент для возможности вручную перезапустить экземпляр процесса из панели для администрирования.

Время нахождения экземпляра процесса в этом статусе определяется настройкой deadLetterJobExpirationTimeSeconds.

deadLetterJobExpirationTimeSeconds: 2592000

Значение параметра по умолчанию – 1 месяц (30 дней).

Настройка префикса для идентификатора экземпляра процесса#

Параметр pidPrefix в конфигурации BPMX позволяет задать префикс для processinstanceid.

Значение параметра по умолчанию не задается. В качестве значения pidPrefix можно использовать значение standId. Для этого в файле bpmx-engine.conf необходимо указать:

bpmx-engine.ose.configmap.application.engine.pidPrefix={{ lookup('custom_vars', 'bpmx.ose.common.stand.id') }

При ручной настройке параметра необходимо внести изменения в файл application.yml (файлы template bpmx-gateway-config.yaml и bpmx-engine-config.yaml) для двух модулей: bpmx-gateway, bpmx-engine.

Ограничения:

1. Длина значения pidPrefix не более 218 символов.

2. В случае превышения допустимого значения в 218 символов pod стартовать не будет.

Пример блока с настройками:

engine:
  pidPrefix: myfavprefix

При такой конфигурации PID в БД будет выглядеть, например, как "myfavprefix_6F9619FF-8B86-D011-B42D-00CF4FC964FF".

Настройка автоматических повторов для REST, JSON-RPC и User Tasks#

Функция автоматических повторов применима для REST Tasks, JSON-RPC Tasks и User Tasks.

Функция автоматических повторов будет выполняться перед политиками повторных вызовов, настроенных вручную.

Для User Tasks функция автоматических повторов будет работать только для запроса прерывания пользовательской задачи.

Настройка функции автоматических повторов производится в блоке engine.http.retry.stateless:

• engine.http.retry.stateless.maxAttempts – количество повторных вызовов;

• engine.http.retry.stateless.minBackOffMills – начальный интервал повтора. Каждый последующий интервал повтора равен: начальный интервал * 2 ^ (номер повтора);

• engine.http.retry.stateless.httpCodesToRetry – список HTTP кодов, при которых будут выполнены повторные вызовы.

engine:
  http:
    retry:
      maxAttempts: 3
      minBackOffMills: 300
      httpCodesToRetry: 429, 502, 503, 504

Настройка интервала планировщика, отвечающего за приостановку и возобновление экземпляров#

Планировщик необходим для простановки соответствующих статусов экземпляров процессов в случае приостановки/активации процесса.

Настройка интервала планировщика, отвечающего за приостановку и возобновление экземпляров, производится в блоке engine.:

• engine.suspend.instances.scheduler.interval – интервал времени в формате ISO8601, через который будет производиться поиск и приостановка/возобновления экземпляров процессов. По умолчанию: PT5S.

Настройка spring actuator#

Блок Management содержит настройки spring actuator, необходимые для формирования метрик мониторинга. Данные настройки присутствуют в сервисах bpmx-engine, bpmx-gateway, bpmx-scheduler в блоке mamagement.

Для настройки доступа к данным spring actuator необходимо указать порт, на котором будут доступны данные: server.port 8888. А также список endpoint, по которым необходимо получать данные.

Настройка Prometheus/Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM)#

Настройка производится в блоке management.

Пример:

management:
  server: 
    port: 8088 
  endpoints:
    enabled-by-default: false
    web.exposure.include: health,metrics,threaddump,prometheus
  endpoint:
    metrics.enabled: true
    health:
      enabled: true
      show-details: always
    threaddump.enabled: true
    prometheus.enabled: true

Для подключения компонента MONA требуется указание дополнительных аннотаций в service.

Список метрик доступен в разделе «События мониторинга».

Настройка spring-части системы#

Настройки присутствуют в файле конфигурации application.yml в сервисах bpmx-engine, bpmx-gateway, bpmx-scheduler в блоке spring.

Должны быть настроены следующие переменные:

• spring

  • main

    • allow-bean-definition-overriding: true

  • cloud

    • config

      • enabled: false – выключение конфигурации через cloud config server (т.е. все настройки будут взяты из текущего файла);

  • application

    • name – наименование сервиса.

Пример:

spring:
  main:
    allow-bean-definition-overriding: true
  cloud:
    config:
      enabled: false
  application:
    name: bpmx-engine

Настройка интеграции с компонентом UTSK#

Настройка подключения к стенду UTSK присутствует в файле конфигурации application.yml в сервисе bpmx-engine в блоке htm.

Для конфигурирования доступны следующие параметры:

• htm

  • engineBalancerHost – url балансировщика BPMX;

  • app

    • url – url основного приложения управления задачами пользователя (UTSK);

Пример:

htm:
  engineBalancerHost: 'https://XXXX.XX'
  app:
    url: 'http://XXXX.XX/htm-portal'

Настройка трассировки#

Структура идентификаторов OpenTracing (трассировка — процесс пошагового выполнения программы) должна позволять отслеживать информацию по бизнес-процессам, исполняемым в среде исполнения BPMX. Информация должна позволять понять, в рамках исполнения какого процесса и на каком шаге был сделан тот или иной удаленный вызов. Для обеспечения такой возможности стандартизирована трансляция определенных HTTP заголовков из входящих запросов в среду исполнения BPMX во все исходящие вызовы, реализованные с помощью поддерживаемых протоколов интеграции. Заголовки трассировки будут сгруппированы в переменной контекста tracingHeaders.

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

• REST API;

• JSON-RPC API.

Настройки работы Tracing осуществляются через файл application.yml в сервисе bpmx-gateway, блок tracing.

Общие настройки для работы трассировки:

• tracing

  • enabled – включение/выключение трассировки;

  • url – URL Tracing-коллектора;

  • name – наименование элемента трассировки;

  • spanKind – вид интервала (span);

  • responseSuccessCode – код успешного ответа от сервера;

  • apiVersion – версия API системы трассировки;

  • threadCount – размер пула потоков для отправки сообщений трассировки.

Настройки фильтрации заголовков:

• useUFSHeaders – использование заголовков ufs-*;

• useMTHeaders – использование заголовков x-mt-*;

• useBaseHeaders – использование заголовков x-*;

• useX3Headers – использование заголовков x-b3-*;

Пример:

tracing:
  enabled: true
  enableTraceIncomingRequests: true
  url: http://some-host:8080/
  name: BPMS
  spanKind: CLIENT
  responseSuccessCode: 202
  apiVersion: 2
  threadCount: 20
  useUFSHeaders: true
  useMTHeaders: true
  useBaseHeaders: true
  useX3Headers: true

Транслируемые заголовки#

Блок настроек Gateway#

Данные параметры доступны для настройки в сервисе Gateway компонента BPMX, блок настроек gateway.

Настройки идемпотентности#

При запуске нового экземпляра процесса пользователь может указать ключ идемпотентности. Если повторно произвести запуск экземпляра процесса в течение определенного времени с тем же ключом идемпотентности, то повторный запуск не производится, пользователю возвращается идентификатор уже запущенного ранее экземпляра процесса. Указанный определенный период времени называется окном идемпотентности и задается в настройках следующим образом:

• gateway.idempotence.windowMs – время окна идемпотентности (в миллисекундах). Если требуется изменить окно идемпотентности, то необходимо расширить значение.

Траблшутинг идемпотентного старта#

1. Если стартовали два разных процесса с одним и тем же ключом:

   • проверьте значение окна идемпотентности и дату старта экземпляров процесса. Возможно, необходимо увеличить окно идемпотентности.

Настройки при переходе процессов из версии 4.х на 5.х#

В связи с тем, что невозможно обеспечить обратную совместимость для версии BPMX 5.х и предыдущих версий BPMX, то для перехода процессов на новую версию необходимо ставить 2 версии BPMX параллельно.

Вариант установки – в одну проектную область (NameSpace) с одним набором Ingress/Egress и разделением трафика через rout и Gateway Service (стоит в версии 5.Х).

Для настройки доступны:

• параметры запуска экземпляров процессов,

• параметры подключения к BPMX версии 4.х.

Параметры запуска экземпляров процессов:

• canary

  • enabled - включение блока настроек (true/false);

  • defaultVersion- версия для запуска экземпляров процессов по умолчанию (4/5);

  • exclusion - список идентификаторов процессов-исключений (будут запускаться в версии, отличной от версии для запуска по умолчанию). Идентификаторы необходимо указывать через запятую.

Рекомендации:

• Если модели процессов еще не установлены в версию 5.х, то необходимо указать версию для запуска по умолчанию – 4.

• Если все модели процессов уже установлены в версию 5.х, то необходимо указать версию для запуска по умолчанию – 5.

• Если часть моделей еще не установлена в версию 5.х (или не надо запускать в версии 5.х), то необходимо указать версию для запуска по умолчанию – 5, а в списке исключений указать идентификаторы процессов, которые еще не установлены в 5.х (или наоборот, например, в зависимости от того, каких процессов больше – установленных в 5.х или 4.х).

Параметры подключения к BPMX версии 4.х:

• engine4g

  • url – это url сервиса engine;

  • datasource – блок настроек для подключения к БД BPMX версии 4.х;

    • driverClassName – имя класса драйвера для подключения к БД;

    • idleTimeout – максимальное время бездействия, по истечении этого времени соединение будет автоматически прервано (мс);

    • jdbcUrl – адрес подключения к БД;

    • maximumPoolSize – максимальное количество соединений в пуле;

    • minimumIdle – минимальное количество незанятых соединений пула;

    • username – имя пользователя;

    • maxLifetime – максимальное время жизни подключения (мс);

    • leakDetectionThreshold – время, в течение которого соединение может быть вне пула, прежде чем будет зарегистрировано сообщение, указывающее на возможную утечку соединения (мс);

    • connectionTimeout – максимальное количество миллисекунд, в течение которых клиент будет ожидать подключения из пула.

Алгоритм маршрутизации запросов:

BPMX1 – компонент BPMX версии 4.x

BPMX2 – компонент BPMX версии 5.x

1. Входящий запрос поступает на Ingress. На нем реализована следующая маршрутизация:

• Если в URL запроса версия API V5, то запрос направляется в BPMX2.

• Если в URL запроса версия API V4 И используется SYSTEM API, то запрос направляется в BPMX2.

• Если в URL запроса версия V4 И используется USER API, то запрос направляется в BPMX1.

• Если используется BPMU (DataIndex) API, то запрос направляется в BPMX2.

2. Поступивший запрос в BPMX2 обрабатывается Gateway Service. На нем установлены следующие дополнительные правила маршрутизации запросов:

• Если это метод для запуска экземпляра процесса, то Gateway Service по идентификатору процесса в настройках сервиса (блок gateway.canary) получает информацию о версии BPMX, в которой необходимо осуществлять запуск. Либо запускает в версии 5.x, либо маршрутизирует на версию 4.x (url в настройке gateway.engine4g.url).

• Если это метод отправки сообщения в экземпляр процесса, то Gateway Service проверяет в базе для BPMX1 (таблица bpmxexecutionentityimpl) наличие экземпляра процесса в BPMX1. Если экземпляр есть в BPMX1, то запрос маршрутизируется в BPMX1 (url в настройке gateway.engine4g.url), иначе обрабатывается в BPMX2.

• Если это метод получения информации об экземпляре процесса (GET /instances/{instanceId}), то Gateway Service маршрутизирует запрос в BPMX1 (url в настройке gateway.engine4g.url) и получает ответ. Если ответ не 200 (ОК), то запрос обрабатывается в BPMX2, иначе возвращается полученный ответ.

• Если это метод отправки сигнала, то запрос маршрутизируется в BPMX1 (url в настройке gateway.engine4g.url) и обрабатывается в BPMX2.

• Если метод GET /signals/{signalName}/readyCount или GET /signals/{signalName}/listReady, то запрос маршрутизируется в BPMX1 (url в настройке gateway.engine4g.url) и обрабатывается в BPMX2.

• Если метод POST /usertasks/notifycomplete или POST /usertasks/notifyabort, то Gateway Service проверяет в базе для BPMX1 (таблица bpmxtaskentityimpl) наличие соответствующей пользовательской задачи в BPMX1. Если задача есть, то запрос маршрутизируется в BPMX1 (url в настройке gateway.engine4g.url), иначе обрабатывается в BPMX2.

• Остальные запросы, поступившие в BPMX2, обрабатываются в BPMX2.

Пример настройки блока gateway:

gateway:
  idempotence.windowMs: 3600000
  canary:
    enabled: true
    defaultVersion: 5
    exclusion: process1,process2,process3
    engine4g:
      url: 'http:\\localhost:8080'
      datasource:
        hikari:
          driverClassName: org.postgresql.Driver
          idleTimeout: 30000
          jdbcUrl: jdbc:postgresql://....
          maximumPoolSize: 100
          minimumIdle: 10
          username: bpmx_ose
          maxLifetime: 1800000
          leakDetectionThreshold: 120000
          connectionTimeout: 11000

Настройка подключения к компоненту BPMU#

Настройки работы с компонентом BPMU осуществляется через настройку взаимодействия с сервисом bpmu-data-index: в файле application.yml в сервисе bpmx-gateway, блок dataindex.

Параметры:

• dataindex

  • url – адрес сервиса bpmu-data-index.

Настройка дросселирования нагрузки#

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

Для настройки дросселирования нагрузки в BPMX необходимо настроить следующие параметры в файле application.yml блок engine:

• engine.startProcessRateLimit.tps— максимальное количество процессов, запускаемых в секунду на одном pod.

• engine.asyncJobRateLimit.tps— максимальное количество AsyncJobs, запускаемых в секунду на одном pod.

Пример:

engine:
  deadLetterJobExpirationTimeSeconds: 2592000
  deadLetterScannerIntervalInSeconds: 300
  alwaysAcknowledge: false
  startProcessRateLimit.tps: 20

Параметр startProcessRateLimit.tps необходим для ограничения скорости вычитывания сообщений из topic bpmx-asyncstart. Минимальное значение вычисляется по формуле: (persistence.asyncStartsTopic.concurrency * persistence.asyncStartsTopic.consumer.properties.max.poll.records * 2 ) / (persistence.kafka.consumer.properties.max.poll.interval.ms / 1000)

Параметр asyncJobRateLimit.tps необходим для ограничения скорости вычитывания сообщений из topic bpmx-asyncjob. Минимальное значение вычисляется по формуле: (persistence.asyncJobsTopic.concurrency * persistence.asyncJobsTopic.consumer.properties.max.poll.records * 2 ) / (persistence.kafka.consumer.properties.max.poll.interval.ms / 1000)

Настройка лимитирования объема данных#

Под лимитированием объема данных понимается возможность задать ограничение на размер системных и бизнес данных экземпляра процесса, занимаемых в хранилище. Настройка лимитирования не является обязательной, но рекомендуемой, так как позволяет обеспечить более стабильный уровень обслуживания.

Вводятся понятия hard limit и soft limit.

Soft limit – ограничение на размер объема данных экземпляра процесса (рекомендуемое), при превышении которого будет отброшено предупреждение в лог-записи.

Hard limit – ограничение на размер объема данных экземпляра процесса (максимум), при превышении которого исполнение процесса будет приостановлено с ошибкой и контекст процесса сохранен не будет.

Параметры конфигурации#

По умолчанию параметры конфигурации, отвечающие за лимитирование не заданы. Рекомендуется провести нагрузочное тестирование исполнения моделей процесса перед настройками конфигурации для определения допустимых значений hard limit и soft limit. Затем полученные значения в байтах внести в следующие параметры в конфигурации приложения bpmx-engine (bpmx-engine.conf):

engine.instanceContextSize.hardLimitBytes
engine.instanceContextSize.softLimitBytes

и следующий параметр приложения bpmx-gateway (bpmx-gateway.conf):

gateway.apiPayloadSize.limitBytes

Описание параметров конфигурации#

Пример сообщений в лог-файлах можно посмотреть в разделе "События системного журнала". Также, помимо логирования превышения ограничений, осуществляется мониторинг объема данных экземпляра при исполнении и при превышении лимитов. Метрики и их описание доступны в разделе "События мониторинга".

Примечание

1. В случае, если экземпляр процесса стартует по сообщению из внешней системы и на это сообщение будет передан payload, превышающий лимит, допустимо прерывание исполнения экземпляра процесса на первом шаге после стартового.

2. Ограничения на payload, задаваемые на bpmx-gateway, отрабатывают только при использовании bpmx-engine версии 5.х. Для приложений более ранних версий функциональность лимитирования недоступна.

Настройка количества экземпляров процессов для массовых операций#

В рамках исполнения операции прерывания или повтора шагов с ошибкой экземпляров процессов предусмотрено задание лимита количества инстансов при массовых операциях.

Использование компонента#

Доставка моделей процессов#

Общая схема#

На схеме выше описан путь доставки моделей процессов до BPMX в зависимости от этапа непрерывной поставки модели на стенд. BPM – централизованный сервис BPMX, в котором исполняются процессы, доставленные от разных потребителей по описанному пути.

Формат поставки#

Плоский zip архив с XML моделями процесса.

Для поставки дистрибутива в платформу архив с моделями должен находиться в каталоге <other/bpmModels.zip>.

Варианты импорта моделей процессов#

Импорт через компонент BPMU#

Есть два возможных сценария:

1. Импорт модели с использованием графического интерфейса компонента BPMU.

2. Импорт модели с использованием CURL через GraphQL.

Оба сценария описаны в Руководстве администратора компонента BPMU.

Импорт с помощью CURL через /system namespace (для загрузки архива)#

Также существует возможность импорта модели с использованием приложения BPMX-Gateway.

1. Необходимо выполнить запрос к BPMX-Gateway:

POST http://укажите URL bpmx-gateway/system/v5/deployments

Необходимо указать следующие параметры в запросе в виде form-data:

–form 'file=@"…/archivename.zip"' (полный путь до архива)

В данном случае Endpoint указывается в самом запросе.

Интеграция с внешними системами#

Интеграция с компонентом Аудит (AUDT) Platform V Audit SE (AUD)#

В связи с требованиями безопасности рекомендуется осуществлять передачу информации о произведенных действиях в компонент AUDT.

Журнал регистрации событий, отправляемых в компонент Аудит, хранится в компоненте AUDT.

В файле конфигурации application.yml в сервисе bpmx-gateway в блоке audit представлены настройки подключения к аудиту:

Взаимодействие производится через Rest API.

Среда исполнения осуществляет отправку следующих данных для фиксации события в компоненте AUDT:

1. Метамодель;

2. Событие.

Вызываемое API:

• Регистрация метамодели

  • $audit_URL/v1/metamodel.

• Отправка события:

  • $audit_URL/v1/event.

Интеграция с компонентом Журналирование (LOGA) Platform V Monitor (OPM)#

Протоколирование операций для их дальнейшего анализа осуществляется в следующую директорию:

-DloggingDir = home/logs
-DloggingJSONFile = log.json

Для отправки событий журнала в sidecar компонента LOGA контейнер должен быть подключен к тому же каталогу, что обеспечит ему возможность чтения и обработки событий.

Для корректного разбора событий необходимо, чтобы формат событий соответствовал шаблону разбора fluent-bit. Формат событий описан в xml-файле конфигурации для библиотеки logback-spring.xml.

logback-spring.xml содержит дополнительные атрибуты:

• traceId – идентификатор trace, с которым связан log (тип строка), получение из заголовка x-b3-traceid.

Запись (log) производится в json формате.

Информация по изменению уровня логирования указана в документе Руководство по установке, «Изменение уровня логирования».

Рекомендации по использованию механизмов безопасности#

В рамках выполнения требований безопасной работы системы рекомендуется:

1. Предоставлять доступ к администрированию только сотрудникам, которым он необходим в соответствии с их должностными обязанностями.

2. Разделять среды разработки, тестирования и эксплуатации.

3. Администраторам системы осуществлять контроль использования средств защиты информации.

4. Использовать компоненты аутентификации, авторизации и аудита в качестве внешних средств защиты.

Управление потоками данных (фильтрация)#

При необходимости включения фильтрации переменных контекста в события Kafka, вычитываемые в целях бизнес-мониторинга, необходимо включить фильтрацию с помощью настройки bpmx-engine.ose.configmap.application.engine.events.filtered.enabled и задать конфигурацию подключения к Kafka из блока bpmx-engine.ose.configmap.application.engine.events.filtered.

В случае включения признака фильтрации запись в настроенные topics будет осуществляться по следующим правилам:

• Если при проектировании модели разработчик процесса не поставил признак наличия доступа к контексту в компоненте BPMD (чек-бокс Доступ к просмотру контекста в окне настройки процесса), то отправка данных в фильтрованный topic будет осуществляться без контекста ("variables": {}). По умолчанию для всех моделей применяется этот механизм.

• Если признак доступа к контексту проставлен, то маскирование осуществляется согласно тегу masked: значения ключей, помеченных тегом masked, полностью скрывается символом *. Количество звездочек равно длине значения. В случае, если ключ - объект или массив, он целиком скрывается одним символом *.

Настройка контроля businessFamily при загрузке моделей процессов#

Для включения валидации заполненности атрибута businessFamily в загружаемой модели необходимо выставить параметр bpmx-gateway.ose.configmap.application.deployer.validation.businessFamily.enabled в значение true, а в параметре bpmx-gateway.ose.configmap.application.deployer.validation.businessFamily.pattern указать регулярное выражение, соответствие которому будет проверяться для businessFamily.

В случае, если при включенном признаке в загружаемой модели не указан businessFamily, либо он не соответствует паттерну, при загрузке будет выведена ошибка.

События системного журнала#

Все события, собираемые компонентом во время работы, публикуются в компоненте LOGA, далее по тексту – Журналирование.

Настройки интеграции с компонентом описаны в разделе «Интеграция с внешними системами».

События регистрируются в формате json. Журнал регистрации событий располагается в АРМ сервиса LOGA. Местоположение АРМ сервиса Журналирования необходимо уточнять у администраторов сред.

Регистрируются события уровней:

• TRACE – менее приоритетные записи (logs) для отладки, с наименьшим уровнем логирования;

• DEBUG – записи (logs), необходимые для отладки приложения. Для уверенности в том, что приложение делает именно то, что от нее ожидают, или описания действия приложения;

• INFO – записи (logs), которые записывают важные действия в приложении. Это не ошибки, это не предостережение, это ожидаемые действия приложения;

• WARN – обозначаются записи (logs), которые содержат предостережение. Произошло неожиданное действие, несмотря на это приложение устояло и выполнило запрос;

• ERROR – уровень ошибок, когда есть проблемы, которые нужно решить. Ошибка не останавливает работу приложения в целом. Остальные запросы могут работать корректно;

• FATAL – ошибка, после которой приложение уже не сможет работать и будет остановлено.

Перечень событий

Трассировка запросов#

В некоторые события логирования после включения и настройки сервиса трассировок (группа настроек tracing) будут добавлены заголовки x-request-chain-id входящих HTTP-запросов. Также при вызове API bpmx-gateway будет отправляться span с фиксацией времени выполнения входящих запросов (при настроенном подключении к сервису трассировок и включенном значении параметра enableTraceIncomingRequests). Настройка категорий логирования осуществляется в файлах bpmx-engine-logback-spring.yaml и bpmx-gateway-logback-spring.yaml для engine и gateway соответственно.

Категории логирования bpmx-engine#

1. Отправка message через ThrowEvent.

<logger name="org.activiti.grid.gain.impl.delegate.KafkaThrowMessageDelegate" level="DEBUG"/>

В сообщении можно посмотреть, что message из экземпляра процесса отправился в Kafka, а также ID экземпляра процесса и наименование сообщения.

[DEBUG] (org.activiti.grid.gain.impl.delegate.KafkaThrowMessageDelegate) [SE. Throw message send. ProcessInstanceId: Process_13849e6. Message: StartProcess]

2. Логирование внешних HTTP вызовов для JSON и RPC Task.

<logger name="org.springframework.web.reactive.function.client.ExchangeFilterFunction" level="DEBUG"/>

В сообщении можно посмотреть ID экземпляра процесса, HTTP метод запроса, url, заголовок и параметры запроса, traceId (уникальный идентификатор запроса в системе tracing, который позволяет в деталях проследить за историей выполнения запроса). TraceId генерируется на HTTP-вызовы, в случае если включен tracing (tracing.enabled: true).

[DEBUG] (org.springframework.web.reactive.function.client.ExchangeFilterFunction) [org.activiti.grid.gain.webclient.WebClientFacade::lambda$logExternalRequestFilter$6:95] mdc:(traceId=null)| SE. External request to http://***. Method: GET. Headers: [Accept:[application/json], Content-Type:[application/json], ott-sberflow-process-id:[Process_13849e6]]. Params: [org.springframework.web.reactive.function.client.WebClient.uriTemplate:http://***, org.springframework.web.reactive.function.client.ClientRequest.LOG_ID:2c5795d0]

3. Логирование внешних вызовов HTM Task.

<logger name="com.sbt.bpms.integration.config.LoggingHtmRequestInterceptor" level="DEBUG"/>

В сообщении можно посмотреть traceId (уникальный идентификатор запроса в системе tracing, который позволяет в деталях проследить за историей выполнения запроса), HTTP метод, заголовки и url запроса. TraceId генерируется на HTTP-вызовы, в случае если включен tracing (tracing.enabled: true).

[DEBUG] (com.sbt.bpms.integration.config.LoggingHtmRequestInterceptor) [com.sbt.bpms.integration.config.LoggingHtmRequestInterceptor::traceRequest:34] mdc:(traceId=null)| SE. Sync mode. Request to HTM: http://***/system/v1/task-templates/<id>/user-task. Method: POST. Headers: [Accept:"text/plain, application/json, application/*+json, */*", Content-Type:"application/json", Content-Length:"774"].

Категории логирования bpmx-gateway#

1. Логирование вызовов API.

<logger name="com.sbt.bpms.configuration.filter.RequestLoggingFilter" level="INFO"/>

В сообщении можно посмотреть HTTP метод, url и заголовки запроса.

[INFO] (com.sbt.bpms.configuration.filter.RequestLoggingFilter) [com.sbt.bpms.configuration.filter.RequestLoggingFilter::beforeRequest:38] mdc:()| GW. Request eb638a7d-a56c-4845-8fb6-b2aef7fd146c started. POST /system/v5/processes/bcb68f52-aac5-4fe6-a683-418840792606, headers=[host:"gateway-pub2-tribe-pc-ift2-bpmx.apps.ocp.devpub.solution.sbt"]

Если включить фильтрацию в logback, то можно смотреть лог-записи только по-данному process definition. Фильтрация включается двумя следующими свойствами:

<property name="loggingByProcessIdEnabled" value="true">
<property name="loggedProcessIds" value="bcb68f52-aac5-4fe6-a683-418840792606">

По умолчанию данные категории имеют уровень логирования "ERROR".

События мониторинга#

Настройки интеграции с компонентом описаны в разделе «Настройка Prometheus/Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM)».

Предварительно потребитель должен создать подключение к компоненту MONA, используя соответствующий resourceName.

Метрики выставляются в формате prometheus. Подробная информация о выставляемых метриках в документации:

• hikaricp;

• JVM;

• Kafka.

Метрики Engine, Gateway и Scheduler

В целях мониторинга ограничения максимально выполняемого количества AsyncJobs в секунду следует:

1. Задать значение настройки bpmx-engine.ose.configmap.application.engine.asyncJobRateLimit.tps

2. Настроить инсталляцию с выбранным ограничением (например, 10 AsyncJobs в секунду), подать нагрузку и по мониторингу увидеть, что количество AsyncJobs не превысило данное значение.

3. Для запущенных экземпляров процессов, которые попали в очередь, при перезапуске подов BPMX не потеряны данные и jobs продолжили свое выполнение.

Часто встречающиеся проблемы и пути их устранения#

Коды ошибок и возможные механизмы устранения#

• SE - отправитель ошибки bpmx-engine

• GW - отправитель ошибки bpmx-gateway

Проблемы с внешними интеграциями#

Алгоритм для диагностирования и решения проблем с внешними интеграциями:

• Проанализируйте журнал BPMX на наличие ошибок/успешных запросов.

• Проанализируйте журнал Istio Proxy в pod сервиса на наличие ошибок/успешных запросов.

• Проанализируйте журнал Egress Gateway на наличие ошибок/успешных запросов.

• Проанализируйте журнал OTT Sidecar на Egress на наличие ошибок/успешных запросов.

Проблемы с пользовательскими задачами#

Алгоритм для диагностирования и решения проблем с пользовательскими задачами (BPMX 5.x):

При исполнении complete для пользовательской задачи может возникать ошибка вида: sbp.bpm.htm.app.service.callback.CallbackException: Callback error: Server returned HTTP response code: 500. В этом случае необходимо изменить настройки модуля bpmx-gateway для параметра canary в файле bpmx-gateway.conf следующим образом: canary: false (по умолчанию в сборке стоит true).

Проблемы при старте процессов#

• При старте процесса экземпляр не отображается на UI, а в лог-файлах присутствует запись [WARN] "Context cache size limit exceeded ({} > {}). New instances will not be started." Необходимо освободить текущий кеш (завершив процессы, находящиеся в статусе Инцидент, если это возможно) или увеличить размер параметра engine.instanceCacheSoftLimit в совокупности с лимитами памяти pod 'bpmx-engine'.

• Процесс стартовал, но его не видно на UI, а в лог-файлах присутствует запись [WARN] (org.activiti.kafka.asyncJobs.JobExecutionManager) [org.activiti.kafka.asyncJobs.JobExecutionManager::getAssignedPartitionNumbers:140] mdc)| There is a difference in assigned asyncJobs and asyncStart partition numbers! Возможные причины проблемы: два стенда bpmx-engine (с разными настройками партиций) настроены на одну Kafka или заведены разные настройки на модулях engine в рамках одного стенда.

• Не стартуют процессы, а в лог-файлах присутствует запись [INFO] (org.activiti.kafka.asyncJobs.JobExecutionManager) [org.activiti.kafka.asyncJobs.JobExecutionManager::startJobExecutionIfPossible:168] mdc)| Context cache size limit exceeded (5042 > 5000). New instances will not be started. Необходимо увеличить значения лимита в конфигурации bpmx-engine (engine.instanceCacheSoftLimit), либо масштабировать решение (увеличить количество pod).

Проблемы с событием получения сообщения#

Если при исполнении экземпляра процесса отбрасывается ошибка "ProcessInstance (processInstanceId=<id>) is not waiting for message with name 'message13_1'", то для отправки сообщения рекомендуется использовать API POST system/v5/instances/{instanceId}/messages/{messageName}.

Ограничение: в случае, если в экземпляре процесса есть несколько шагов на получение сообщения с одинаковым messageName, но разным payload, исполнение такого процесса может встать в ошибку. Не рекомендуется использовать одинаковый messageName при неодинаковом payload.

Проблема зависания экземпляров при рестарте pod engine#

При большом количестве экземпляров в незавершенном статусе, при рестарте pod engine есть вероятность зависания экземпляров процессов.

Решение:

Изменить значения конфигурационного параметра bpmx-engine contextLoadPartitionIdleEventMs с 20000 на 40000.

Проблемы при исполнении экземпляров процесса#

Экземпляр процесса исполнился, но не видно исполнение на UI. Возможная причина: ошибка сериализации данных. Необходимо проверить лог-записи на наличие записи com.fasterxml.jackson.databind.exc.InvalidDefinitionException: Type id handling not implemented for type java.lang.Object (by serializer of type com.fasterxml.jackson.databind.ser.impl.UnsupportedTypeSerializer). В случае, если запись найдена, необходимо проанализировать контекст экземпляра процесса и в случае, если это уместно, пересмотреть типизацию данных в модели. В противном случае обратиться к разработчикам сервиса.

В случае возникновения ответа от REST Task:

process instance was failed errorCode = ACTIVITY_EXCEPTION Did not observe any item or terminal signal within 10000ms in 'flatMap' (and no fallback has been configured) [Original exception: org.activiti.grid.gain.impl.exception.HttpTaskExceptionWrapper, Nested exception: org.activiti.engine.ActivitiException]

необходимо проверить доступность вызываемого сервиса или увеличить значение тайм-аута в модели.