This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 4ca3aedac [#5304] doc(core): add event listener document (#5307)
4ca3aedac is described below
commit 4ca3aedac69f7a72ea1dd1ee3fb68879166171a7
Author: FANNG <[email protected]>
AuthorDate: Tue Oct 29 10:56:46 2024 +0800
[#5304] doc(core): add event listener document (#5307)
### What changes were proposed in this pull request?
add event listener document
### Why are the changes needed?
Fix: #5304
### Does this PR introduce _any_ user-facing change?
no
### How was this patch tested?
just document
---
docs/gravitino-server-config.md | 31 +++++++++++++++++++++----------
docs/iceberg-rest-service.md | 6 ++++++
2 files changed, 27 insertions(+), 10 deletions(-)
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index 9d319d289..a7c696051 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -113,16 +113,27 @@ To leverage the event listener, you must implement the
`EventListenerPlugin` int
#### Event
-Gravitino triggers a specific event upon the completion of the operation, with
varying events being generated for different operations.
+Gravitino triggers a pre-event before the operation, a post-event after the
completion of the operation and a failure event after the operation failed.
-| operation type | event
|
-|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| table operation | `CreateTableEvent`, `AlterTableEvent`,
`DropTableEvent`, `LoadTableEvent`, `ListTableEvent`, `PurgeTableFailureEvent`,
`CreateTableFailureEvent`, `AlterTableFailureEvent`, `DropTableFailureEvent`,
`LoadTableFailureEvent`, `ListTableFailureEvent`, `PurgeTableFailureEvent` |
-| fileset operation | `CreateFileSetEvent`, `AlterFileSetEvent`,
`DropFileSetEvent`, `LoadFileSetEvent`, `ListFileSetEvent`,
`CreateFileSetFailureEvent`, `AlterFileSetFailureEvent`,
`DropFileSetFailureEvent`, `LoadFileSetFailureEvent`, `ListFileSetFailureEvent`
|
-| topic operation | `CreateTopicEvent`, `AlterTopicEvent`,
`DropTopicEvent`, `LoadTopicEvent`, `ListTopicEvent`,
`CreateTopicFailureEvent`, `AlterTopicFailureEvent`, `DropTopicFailureEvent`,
`LoadTopicFailureEvent`, `ListTopicFailureEvent`
|
-| schema operation | `CreateSchemaEvent`, `AlterSchemaEvent`,
`DropSchemaEvent`, `LoadSchemaEvent`, `ListSchemaEvent`,
`CreateSchemaFailureEvent`, `AlterSchemaFailureEvent`,
`DropSchemaFailureEvent`, `LoadSchemaFailureEvent`, `ListSchemaFailureEvent`
|
-| catalog operation | `CreateCatalogEvent`, `AlterCatalogEvent`,
`DropCatalogEvent`, `LoadCatalogEvent`, `ListCatalogEvent`,
`CreateCatalogFailureEvent`, `AlterCatalogFailureEvent`,
`DropCatalogFailureEvent`, `LoadCatalogFailureEvent`, `ListCatalogFailureEvent`
|
-| metalake operation | `CreateMetalakeEvent`, `AlterMetalakeEvent`,
`DropMetalakeEvent`, `LoadMetalakeEvent`, `ListMetalakeEvent`,
`CreateMetalakeFailureEvent`, `AlterMetalakeFailureEvent`,
`DropMetalakeFailureEvent`, `LoadMetalakeFailureEvent`,
`ListMetalakeFailureEvent` |
+##### Post-event
+
+| Operation type | Post-event
| Since Version |
+|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
+| table operation | `CreateTableEvent`, `AlterTableEvent`,
`DropTableEvent`, `LoadTableEvent`, `ListTableEvent`, `PurgeTableFailureEvent`,
`CreateTableFailureEvent`, `AlterTableFailureEvent`, `DropTableFailureEvent`,
`LoadTableFailureEvent`, `ListTableFailureEvent`, `PurgeTableFailureEvent`
| 0.5.0 |
+| fileset operation | `CreateFileSetEvent`,
`AlterFileSetEvent`, `DropFileSetEvent`, `LoadFileSetEvent`,
`ListFileSetEvent`, `CreateFileSetFailureEvent`, `AlterFileSetFailureEvent`,
`DropFileSetFailureEvent`, `LoadFileSetFailureEvent`, `ListFileSetFailureEvent`
| 0.5.0 |
+| topic operation | `CreateTopicEvent`, `AlterTopicEvent`,
`DropTopicEvent`, `LoadTopicEvent`, `ListTopicEvent`,
`CreateTopicFailureEvent`, `AlterTopicFailureEvent`, `DropTopicFailureEvent`,
`LoadTopicFailureEvent`, `ListTopicFailureEvent`
| 0.5.0 |
+| schema operation | `CreateSchemaEvent`,
`AlterSchemaEvent`, `DropSchemaEvent`, `LoadSchemaEvent`, `ListSchemaEvent`,
`CreateSchemaFailureEvent`, `AlterSchemaFailureEvent`,
`DropSchemaFailureEvent`, `LoadSchemaFailureEvent`, `ListSchemaFailureEvent`
| 0.5.0 |
+| catalog operation | `CreateCatalogEvent`,
`AlterCatalogEvent`, `DropCatalogEvent`, `LoadCatalogEvent`,
`ListCatalogEvent`, `CreateCatalogFailureEvent`, `AlterCatalogFailureEvent`,
`DropCatalogFailureEvent`, `LoadCatalogFailureEvent`, `ListCatalogFailureEvent`
| 0.5.0 |
+| metalake operation | `CreateMetalakeEvent`,
`AlterMetalakeEvent`, `DropMetalakeEvent`, `LoadMetalakeEvent`,
`ListMetalakeEvent`, `CreateMetalakeFailureEvent`, `AlterMetalakeFailureEvent`,
`DropMetalakeFailureEvent`, `LoadMetalakeFailureEvent`,
`ListMetalakeFailureEvent`
| 0.5.0 |
+| Iceberg REST server table operation | `IcebergCreateTableEvent`,
`IcebergUpdateTableEvent`, `IcebergDropTableEvent`, `IcebergLoadTableEvent`,
`IcebergListTableEvent`, `IcebergTableExistsEvent`, `IcebergRenameTableEvent`,
`IcebergCreateTableFailureEvent`, `IcebergUpdateTableFailureEvent`,
`IcebergDropTableFailureEvent`, `IcebergLoadTableFailureEvent`,
`IcebergListTableFailureEvent`, `IcebergRenameTableFailureEvent`,
`IcebergTableExistsFailureEvent` | 0.7.0-incubating |
+
+##### Pre-event
+
+Pre-event is only generated before Iceberg REST server table operations, the
other operation doesn't generate pre-event for now.
+
+| Operation type | Pre-event
| Since Version |
+|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
+| Iceberg REST server table operation | `IcebergCreateTablePreEvent`,
`IcebergUpdateTablePreEvent`, `IcebergDropTablePreEvent`,
`IcebergLoadTablePreEvent`, `IcebergListTablePreEvent`,
`IcebergTableExistsPreEvent`, `IcebergRenameTablePreEvent` | 0.7.0-incubating |
#### Event listener plugin
@@ -136,7 +147,7 @@ The plugin provides several operational modes for how to
process event, supporti
- **ASYNC_ISOLATED**: Events are processed asynchronously, with each listener
having its own dedicated queue and dispatcher thread. This approach offers
better isolation but at the expense of multiple queues and dispatchers.
-For more details, please refer to the definition of the plugin.
+When processing pre-event, you could throw a `ForbiddenException` to skip the
following executions. For more details, please refer to the definition of the
plugin.
### Audit log configuration
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index ad44a2014..01f651449 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -18,6 +18,7 @@ The Apache Gravitino Iceberg REST Server follows the [Apache
Iceberg REST API sp
- pagination
- Works as a catalog proxy, supporting `Hive` and `JDBC` as catalog backend.
- Supports different storages like `S3`, `HDFS`, `OSS`, `GCS` and provides the
capability to support other storages.
+- Supports event listener.
- Supports OAuth2 and HTTPS.
- Provides a pluggable metrics store interface to store and delete Iceberg
metrics.
@@ -299,6 +300,11 @@ The `clients` property for example:
`catalog-impl` has no effect.
:::
+
+### Event listener
+
+Gravitino generates pre-event and post-event for table operations and provide
a pluggable event listener to allow you to inject custom logic. For more
details, please refer to [Event listener
configuration](gravitino-server-config.md#event-listener-configuration).
+
### Apache Iceberg metrics store configuration
Gravitino provides a pluggable metrics store interface to store and delete
Iceberg metrics. You can develop a class that implements
`org.apache.gravitino.iceberg.service.metrics.IcebergMetricsStore` and add the
corresponding jar file to the Iceberg REST service classpath directory.
