Skip to main content
Version: 1.9.0

Event bus

Overview​

Jadice flow uses an internal event bus for the following use cases:

  • Workers send events like worker active count. Controller sends job / step events. Those events are received by the UI or controller for example, to update internal data structures.
  • Auto-Discovery of workers - auto-registration will be performed by the worker so no configuration of a workers.yaml is needed anymore

Event bus​

The third party middleware Hazelcast is used for the event bus. It allows flow componenty to dynamically form a cluster to send notifications. It is also base for auto-discovery (which can be enabled separately).

In the controller, it can be enabled via application.yaml:

# Jadice flow main config
jadice-flow:
  # Event bus configuration:
  # Event bus is used for auto-discovery / worker auto-registration (and events like worker-active-count)
  event-bus:
    enabled: true
    # The hazelcast configuration file from the classpath. A custom configuration could be placed in the
    # application classpath to change it.
    #
    # The default configuration from jf-event-bus will use multicast port 54327 for auto-discovery. 
    # Events will be sent via TCP Port 5701
    configFile: hazelcast-config.yml
    # Simple list of names (regex) for event classes to exclude from being broadcast
    # to the event bus. This only affects filtering for sending the event. No filters are applied inside
    # the event bus when receiving a message. This is done in the listeners.
    #
    # This can be useful to reduce message count on the event bus. For example, if the UI is not used (often),
    # PartEvents and ItemEvents could be disabled in the controller.
    #
    # Some useful Event types (see in jf-event-bus the package com.jadice.flow.controller.event.types):
    # JobEvent, ItemEvent, PartEvent, StepEvent, SystemStatusEvent, WorkerActiveCountChangedEvent,
    # WorkerRegistrationEvent
    # 
    # Item/Part events can be disabled if no live updates are required in the UI (There are still the
    # Step+JobEvents).
    excludedEventClasses:
    - "ItemEvent"
    - "PartEvent"

Settings:

  • jadice-flow.event-bus.enabled - whether to enable the event bus
  • jadice-flow.event-bus.configFile - path to the hazelcast configuration file in the classpath

As noted in the comments, Events will be sent via TCP Port 5701. Multicast port 54327 for auto-discovery.

This is configured in a hazelcast-configuration file. A custom file can also be placed in the application classpath and referenced in the application.yml to change the configuration.

The current default configuration (hazelcast-config.yml) looks like

hazelcast:
  cluster-name: jf-hazel-cluster
  properties:
    hazelcast.discovery.enabled: true
  listeners:
    # AutoDiscovery Membership listener will notify via internal MembersChangedEvent about Member change
    - com.jadice.flow.controller.event.bus.ADMembershipListener
  network:
    join:
      auto-detection:
        enabled: true
# multicast-group: The multicast group IP address. Specify it when you want to create clusters within
# the same network. Values can be between 224.0.0.0 and 239.255.255.255. Its default value is 224.2.2.3.
      multicast:
        enabled: true
        multicast-group: 224.2.2.3
        multicast-port: 54327

A full example for a configuration file and additional infos can also be found in the Hazelcast GitHub repo

Auto discovery​

Usually, a workers.yaml file has to be configured in the Jadice Flow Controller which defines what types of workers are available. It contains the URLs for the worker and also which configuration parameters are available for the worker.

To simplify the configuration, auto discovery can be enabled. If enabled, no workers.yml has to be configured on the controller side. Workers will auto-register themselves when started. If the controller has to be restarted, it will automatically request the workers to re-register.

When workers register, their possible WorkerDefinitions (containing the configuration parameters) are cached on the controller side. This allows to configure steps for the worker later on, even if no worker instance is currently running. Cached worker definitions can be cleaned automatically, if no worker registers for this type for a certain amount of time (default=120 days).

UI​

In the UI, there is a new cluster view which shows the recognized worker instances (if no auto discovery is enabled, this view shows the configured workers from workers.yaml). Cluster view

It mainly shows:

  • Worker application name
  • URL and instance ID
  • Helm Chart and / or Application Version if available
  • Current Active Work count (will be updated automatically)

The automatic update intervals of the cluster view panel can be configured via application.yml of the UI:

jadice-flow-ui:
  clusterView:
    minTimeBetweenAvailabilityUpdatesMS: 30000
    minTimeBetweenWorkCountUpdatesMS: 500

In this default configuration:

  • minTimeBetweenAvailabilityUpdatesMS: Will update the availability column at max rate of 30sec (depends on the availability service)
  • WorkCountActive Messages from workers will trigger an update of the workActive column at max rate of 500ms

Controller side configuration​

In the default application.yml of the controller, auto-discovery will be automatically enabled if the event bus is enabled (jadice-flow.event-bus.enabled referenced below):

jadice-flow:
  # AutoDiscovery can be enabled if the event-bus is enabled. Workers will auto-register themselves
  # (no need for workers.yaml anymore).
  auto-discovery:
    enabled: ${jadice-flow.event-bus.enabled}
    # Auto-scale the parallel job count based on the available max worker instances
    updateParallelJobCountBasedOnWorkers: false
    # Updates the worker service pool in the controller based on the available max worker instances
    # (updates jadice-flow.system.maximumConcurrentWorkerInvocationsSpecific for the worker type)
    # This should generally be enabled; otherwise the controller might not use all or too many instances
    # when workers are scaled.
    updateWorkerServicePool: true
    # When a worker registers, the worker definition will be cached in the DB. (This way, the UI can for
    # example still be used to configure the worker, even if it is not running)
    # This property defines, when a cached worker definition shall be removed, if no worker registered
    # in the given time.
    # If the cache time is 0, caching is disabled
    workerDefCacheTime: 120d
    ## Run once every 8 hours.
    cronSchedule: "0 * */8 * * *"

Settings:

  • jadice-flow.auto-discovery.enabled - to enable auto discovery (controller listens for Member Changes and Registration Events)
  • jadice-flow.auto-discovery.workerDefCacheTime - when a worker registers, its provided worker definition will be cached in the database for the given amount of time. If no worker of the given type is registered within this duration, a Cached Definition would be deleted again. Default 120 days. A cached configuration allows for example that the step can still be configured via the UI, even if the worker is currently not running.
  • jadice-flow.auto-discovery.cronSchedule - when to check for old cached entries to clean up (default every 8h)

Note

  • jadice-flow.auto-discovery.updateParallelJobCountBasedOnWorkers - is an experimental feature which allows to automatically set the parallel job count based on the maximum available worker count for a type. This requires the workers to have the "maxWorkerRequests"-Property in application.yaml set to a value > 0. For example, a toPDF-Worker could be set to 4 max requests. If 2 workers are available, the controller would use a parallel job count of 8; this would automatically scale up or down based on worker instances.

Worker side configuration​

To enable auto-discovery on the worker side, there is also a configuration in the application.yml.

There are no "jadice-flow.auto-discovery"-Settings on the worker side - it is only needed to enable the event bus here. Auto-discovery is enabled automatically in the worker if event bus is enabled.

jadice-flow:
  # Event bus configuration: 
  # AutoDiscovery is enabled if the event-bus is enabled. 
  # Workers will auto-register themselves at the controller (no need for workers.yaml anymore)
  #
  # Event bus is used for auto-discovery / worker auto-registration (and events like worker-active-count)
  event-bus:
    enabled: true
    # The hazelcast configuration file from the classpath. A custom configuration could be placed in the
    # application classpath to change it.
    #
    # The default configuration from jf-event-bus will use multicast port 54327 for auto-discovery. 
    # Events will be sent via TCP Port 5701
    configFile: hazelcast-config.yml

The hazelcast configuration file is the same as in the controller.

Note for Worker URL resolving​

The worker will propagate its URL to the controller based on the local host name. In some cases it might be needed to set a specific host name on the worker.

This can be done by setting the environment variable K8S_POD_IP to the desired value.

Configuration via Helm​

The event bus and auto discovery are enabled by default in all jadice flow Helm charts. You can easily switch back to using a workers.yaml for the registration by applying these changes to the values.yaml

# disable event bus for the workers
global:
  jadiceFlow:
    disableEventBus: true

# disable event bus for the controller
jf-controller:
  # 1. uncomment the line with the vale 'workersConfigMap'
  workersConfigMap: jf-email-conversion-workers
  # 2. set eventBus.enabled to false
  eventBus:
    enabled: false
Last updated on by Simon Welsch