[incubator-kyuubi] branch master updated: [KYUUBI #3179] Add custom event handler docs

[ul...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ulyssesyou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-kyuubi.git


The following commit(s) were added to refs/heads/master by this push:
     new c79775036 [KYUUBI #3179] Add custom event handler docs
c79775036 is described below

commit c79775036b82679d5677ba2459c0efa5e87df63b
Author: Min <zh...@163.com>
AuthorDate: Fri Sep 9 10:00:27 2022 +0800

    [KYUUBI #3179] Add custom event handler docs
    
    ### _Why are the changes needed?_
    
    ### _How was this patch tested?_
    - [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible
    
    - [ ] Add screenshots for manual tests if appropriate
    
    - [ ] [Run test](https://kyuubi.apache.org/docs/latest/develop_tools/testing.html#running-tests) locally before make a pull request
    
    Closes #3179 from zhaomin1423/custom_event_doc.
    
    Closes #3179
    
    9456c997 [Xiao Zhao] fix
    2e6f3030 [Xiao Zhao] fix
    c13bdb5b [Min] update
    ff88386e [Min] fix
    38a5708d [Min] Add custom event handler docs
    
    Lead-authored-by: Min <zh...@163.com>
    Co-authored-by: Xiao Zhao <zh...@163.com>
    Signed-off-by: ulysses-you <ul...@apache.org>
---
 docs/extensions/server/events.rst | 67 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/docs/extensions/server/events.rst b/docs/extensions/server/events.rst
index b5d484c8f..832c1e5df 100644
--- a/docs/extensions/server/events.rst
+++ b/docs/extensions/server/events.rst
@@ -13,10 +13,69 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
-Handle Events with Custom Event Handler
+Configure Kyuubi to use Custom EventHandler
 =======================================
 
-.. caution:: unstable
+Kyuubi provide event processing mechanism, it can help us to record some events. Beside the builtin ``JsonLoggingEventHandler``,
+Kyuubi supports custom event handler. It is usually used to write Kyuubi events to some external systems.
+For example, Kafka, ElasticSearch, etc. The ``org.apache.kyuubi.events.handler.CustomEventHandlerProvider`` has a zero-arg constructor,
+it can help us to create a custom EventHandler.
 
-.. warning::
-   This page is still in-progress.
+.. code-block:: scala
+
+   package org.apache.kyuubi.events.handler
+
+   import org.apache.kyuubi.config.KyuubiConf
+   import org.apache.kyuubi.events.KyuubiEvent
+
+   /**
+    * Custom EventHandler provider. We can implement it to provide a custom EventHandler.
+    * The implementation will be loaded by ``Service Provider Interface``.
+    */
+   trait CustomEventHandlerProvider {
+
+     /**
+      * The create method is called to create a custom event handler
+      * when this implementation is loaded.
+      *
+      * @param kyuubiConf The conf can be used to read some configs.
+      * @return A custom handler to handle KyuubiEvent.
+      */
+      def create(kyuubiConf: KyuubiConf): EventHandler[KyuubiEvent]
+   }
+
+Build A Custom EventHandler
+----------------------------
+
+To create custom EventHandlerProvider class derived from the above interface, we need to:
+
+- Referencing the library
+
+.. code-block:: xml
+
+   <dependency>
+      <groupId>org.apache.kyuubi</groupId>
+      <artifactId>kyuubi-event_2.12</artifactId>
+      <version>1.7.0-incubating</version>
+      <scope>provided</scope>
+   </dependency>
+
+- Implement ``org.apache.kyuubi.events.handler.CustomEventHandlerProvider``
+- Adding a file named ``org.apache.kyuubi.events.handler.CustomEventHandlerProvider`` in the src/main/resources/META-INF/services folder of project, its content is the custom class name.
+
+Enable Custom EventHandler
+----------------------------
+
+To enable the custom EventHandler, we need to
+
+- Put the jar package to ``$KYUUBI_HOME/jars`` directory to make it visible for
+    the classpath of the kyuubi server.
+- Configure the following properties to ``$KYUUBI_HOME/conf/kyuubi-defaults.conf``
+  on each node where kyuubi server is installed. If you need use other event handler, it can be appended after the ``CUSTOM``.
+
+.. code-block:: property
+   :margin:
+
+   kyuubi.backend.server.event.loggers=CUSTOM
+
+- Restart all the kyuubi server instances.