Observation Module

The Observation Module provides APIs to listen to internal XWiki events that are being executed, like document creation or document change. Events can have 2 sources:

  • local sources, from other XWiki modules
  • remote sources, from other servers

Local Observation Module

The local Observation module allows listening to internal XWiki events, including custom ones. The API is published on GitHub and allows:

  • listening to all event types
  • listening to a particular event type like document creation, document update or document rollback; the complete list is available here
  • to register event listeners either automatically as component or programmatically 
  • to programmatically unregister event listeners 
  • sending events to all listeners


1. Groovy Event Notifications
2. Post Processing Groovy Event Listener
3. Observe document save events in the wiki and fire a custom user created event when the saved document is a user document.
4. Tag an event as "fold" which means it will be sent by a task that generates some events during its execution.

Remote Observation Module

The remote Observation module allows to automatically send and receive events through the network. The API is published on GitHub and provides the way to:

  • start and stop channels at runtime
  • add custom event converters
  • add custom network adapter implementation

Currently, the default network adapter implementation is based on JGroups. The channel configuration is first searched in the  WEB-INF/observation/remote/jgroups/<channel name>.xml file, then in the <channel name>.xml file located in the root of the jgroups JAR file.


The general configuration is available in the "WEB-INF/xwiki.properties" file, under "Events distribution":

#-# [Since 2.0M3]
#-# Indicate if the network distribution module is enabled or not.
#-# By default remote events are disabled.
# observation.remote.enabled = false

#-# [Since 2.0M3]
#-# The list of events communication channels to start when the application starts.
#-# By default no channel is configured.
#-# The default remote event distribution implementation is using JGroups and you'll need to either use embedded JGroups configuration
#-# files or drop your custom configuration in the WEB-INF/observation/remote/jgroups/ directory.
#-# There's a README file in that directory with more information.
#-# Example: observation.remote.channels = public, cluster

#-# [Since 2.0M4]
#-# The implementation of network adapter to use.
#-# The default is jgroups.
#-# By default only jgroups is provided. To add one implements NetworkAdaptor component interface. The identifier provided in the configuration is matched with the component role hint.
#-# Example: observation.remote.networkadapter = jgroups



To diagnose clustering issues, you can enable 2 types of logs:

  • the XWiki cluster logs by setting log4j.logger.org.xwiki.observation.remote on TRACE in the Logging Application
  • the JGroups logs by following these instructions


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space