diff --git a/documentation/modules/ROOT/assets/images/jmx-notification-attribute.png b/documentation/modules/ROOT/assets/images/jmx-notification-attribute.png new file mode 100644 index 000000000..39678bae6 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/jmx-notification-attribute.png differ diff --git a/documentation/modules/ROOT/assets/images/jmx-signal-operation.png b/documentation/modules/ROOT/assets/images/jmx-signal-operation.png new file mode 100644 index 000000000..da3130b0d Binary files /dev/null and b/documentation/modules/ROOT/assets/images/jmx-signal-operation.png differ diff --git a/documentation/modules/ROOT/pages/configuration/notification.adoc b/documentation/modules/ROOT/pages/configuration/notification.adoc index e6d8d7999..61c657d1d 100644 --- a/documentation/modules/ROOT/pages/configuration/notification.adoc +++ b/documentation/modules/ROOT/pages/configuration/notification.adoc @@ -17,8 +17,9 @@ endif::community[] {prodname} notifications provide a mechanism to obtain status information about the connector. Notifications can be sent to the following channels: -SinkNotificationChannel:: Notifications are sent through the Connect API to a configured topic. -LogNotificationChannel:: Notification are appended to the log. +SinkNotificationChannel:: sends notifications through the Connect API to a configured topic. +LogNotificationChannel:: notifications are appended to the log. +JmxNotificationChannel:: notifications are exposes as an attribute in a JMX bean Custom:: Notifications are sent to a xref:debezium-notification-custom-channel[custom channel] that you implement. @@ -183,9 +184,30 @@ By default, the following notification channels are available: * `sink` * `log` +* `jmx` To use the `sink` notification channel, you must also set the `notification.sink.topic.name` configuration property to the name of the topic where you want {prodname} to send notifications. +// Type: procedure +[id="access-debezium-jmx-notifications"] +=== Access to {prodname} JMX notifications + +To access to notification provided through JMX bean you need to: + +* xref:operations/monitoring.adoc[enable JMX MBeanServer] to expose the notification bean +* add `jmx` to the `notification.enabled.channels` configuration property. +* connect with your preferred client to MBeanServer + +Notifications are exposed in the bean named `debezium..management.notifications.` through the `Notifications` attribute. + +The image below shows the notification about the start of the incremental snapshot + +image::jmx-notification-attribute.png[JMX notification attribute] + +You can also `reset` the notifications calling the `reset` operation on the bean. + +The notifications are also exposed as a JMX notification with type `debezium.notification`. You can link:https://www.ibm.com/docs/en/streams/4.1.1?topic=streams-processing-jmx-api-notifications[subscribe to receive these notifications] in your application. + // Type: concept [id="debezium-notification-custom-channel"] == Custom notification channels diff --git a/documentation/modules/ROOT/pages/configuration/signalling.adoc b/documentation/modules/ROOT/pages/configuration/signalling.adoc index 8f49460fa..4f048372a 100644 --- a/documentation/modules/ROOT/pages/configuration/signalling.adoc +++ b/documentation/modules/ROOT/pages/configuration/signalling.adoc @@ -17,9 +17,10 @@ endif::community[] The {prodname} signaling mechanism provides a way to modify the behavior of a connector, or to trigger a one-time action, such as initiating an xref:debezium-signaling-ad-hoc-snapshots[ad hoc snapshot] of a table. To use signals to trigger a connector to perform a specified action, you can configure the connector to use one or more of the following channels: -SourceSignalChannel:: You can issue a SQL command to add a signal message to a specialized signaling {data-collection}. -The signaling {data-collection}, which you create on the source database, is designated exclusively for communicating with {prodname}. +SourceSignalChannel:: You can issue a SQL command to add a signal message to a specialized signaling data-collection. +The signaling data-collection, which you create on the source database, is designated exclusively for communicating with {prodname}. KafkaSignalChannel:: You submit signal messages to a configurable Kafka topic. +JmxSignalChannel:: You submit signal through the `signal` JMX operation. Custom:: You submit signals to a xref:debezium-custom-signaling-channel[custom channel] that you implement. When {prodname} detects that a new xref:debezium-signaling-example-of-a-logging-record[logging record] or xref:debezium-signaling-example-of-an-ad-hoc-signal-record[ad hoc snapshot record] is added to the channel, it reads the signal, and initiates the requested operation. @@ -193,6 +194,51 @@ Key = `test_connector` Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.table1", "schema1.table2"], "type": "INCREMENTAL"}}` ---- +// Type: procedure +// Title: Enabling the {prodname} JMX signaling channel +[id="debezium-signaling-enabling-jmx-signaling-channel"] +== Enabling JMX signaling channel + +You can enable the JMX signaling channel by adding `jmx` to the `signal.enabled.channels` configuration property. + +Then you need xref:operations/monitoring.adoc[to enable JMX MBeanServer] to expose the signaling bean. + +=== Send signal + +First of all, you need to connect to the `MBeanServer` through your preferred tool (i.e. jconsole, JDK Mission Control) , then you need to search for a bean named `debezium..management.signals.` + +This bean expose the `signal` operation that take in input three parameters: + +p0:: id of the signal +p1:: type of the signal for example `execute-snapshot` +p2:: json data field that contains additional information for the specific signal type. + +When the signal type is set to `execute-snapshot`, the `data` field must include the fields that are listed in the following table: + +.Execute snapshot data fields +[cols="2,2,6",options="header"] +|=== +|Field | Default | Value + +|`type` +|`incremental` +| The type of the snapshot to run. +Currently {prodname} supports only the `incremental` type. + +|`data-collections` +|_N/A_ +| An array of comma-separated regular expressions that match the fully-qualified names of the tables to include in the snapshot. + +Specify the names by using the same format as is required for the xref:{context}-property-signal-data-collection[signal.data.collection] configuration option. + +|`additional-condition` +|_N/A_ +| An optional string that specifies a condition that the connector evaluates to designate a subset of records to include in a snapshot. +|=== + +The following image shows how to send signal from `jconsole` + +image::jmx-signal-operation.png[] + // Type: concept [id="debezium-custom-signaling-channel"] == Custom signaling channel