CREATE EVENT MONITOR（程序包高速缓存）语句

CREATE EVENT MONITOR (程序包高速缓存) 语句创建一个事件监视器，该事件监视器将在从程序包高速缓存中清空部分的高速缓存条目时记录事件。

注意：随着Db2 12.1 的发布，包缓存事件监控器的 UNFORMATTED EVENT TABLE 目标选项已被弃用，并可能在未来的版本中删除。相反，请使用 "写入目标 "选项。

调用

此语句可嵌入应用程序中或者以交互方式发出。它是一个可执行语句，仅当 DYNAMICRULES 运行行为对于程序包有效时才能动态编译 (SQLSTATE 42509)。事件监控器只能在 SYSTEM 租户中定义（SQLSTATE 58004）。

授权

该语句的授权标识所拥有的特权必须包括以下权限之一：

DBADM 权限
SQLADM 权限

描述

事件监测器名称事件监视器的名称。这是一部分名称。它是普通或定界 SQL 标识。 event-monitor-name 不得标识目录中已存在的事件监视器 (SQLSTATE 42710)。

FOR

指示要记录的事件类型。

PACKAGE CACHE: 指定当从程序包高速缓存中清空静态或动态 SQL 语句的高速缓存条目时，此事件监视器将记录事件。此事件监视器不是被动的，一旦激活，将开始记录事件。

过滤和收集选项指定一组过滤器和集合选项。

WHERE

事件条件定义一个过滤器，用于确定从程序包高速缓存中清空的条目是否应导致发生事件。如果要从程序包高速缓存中清空的特定条目的事件条件为 TRUE ，那么该条目将记录为事件。

此子句是 WHERE 子句的特殊形式，不应与标准搜索条件混淆。这是一个简单的 WHERE 子句，它包括使用 NOT ， OR 和 LIKE 运算符，与为 CONNECTIONS ， TRANSACTIONS 和 STATEMENTS 事件监视器指定的 WHERE 子句不同。

如果未指定 WHERE 子句，那么将监视从程序包高速缓存中清空的所有条目。

更新时间

指定此事件监视器应收集已逐出的条目 (其度量在边界时间之后更新)。通过调用 MON_GET_PKG_CACHE_STMT 表函数并将输入键 "updated_boundary_time" 的值设置为此事件监视器的名称来设置边界时间。

边界时间最初设置为事件监视器的激活时间戳记。

NUM_EXECUTIONS > | < | <= | = | >= 整数常量

指定应将监视元素 num_executions 与 integer-constant 进行比较，以确定是否生成事件。 NUM_RESOURCES 是执行已逐出条目的部分的次数。

注: num_executions 监视元素对语句的所有执行进行计数，无论语句的执行是否有助于报告的活动度量值。

STMT_EXEC_TIME > | < | <= | = | >= 整数常量

指定应将监视元素 stmt_exec_time 与 integer-constant 进行比较，以确定是否生成事件。 STMT_EXEC_TIME 是执行逐出条目的语句所耗用的总聚集时间。必须将 integer-constant 的时间单位指定为毫秒。

COLLECT BASE DATA

指定应该捕获 MON_GET_PKG_CACHE_STMT 表函数返回的相同级别的信息。这是缺省收集选项。

COLLECT DETAILED DATA

指定应该收集 BASE 级别信息以及清空条目的运行时可执行部分。

WRITE TO

指定数据的目标。

表

指示事件监视器数据的目标是一组数据库表。事件监视器将数据流分成一个或多个逻辑数据组，并将每个组插入到单独的表中。将保留具有目标表的组的数据，并丢弃没有目标表的组的数据。该组中包含的每个监视器元素都会映射到同名的表列。只会将具有对应表列的元素插入到该表中。将丢弃其他元素。

formatted-event-table-info

定义事件监视器的目标格式化事件表。此子句应指定要记录的每个分组。但是，如果未指定 evm-group 子句，那么将记录事件监视器类型的所有组。

有关逻辑数据组的更多信息，请参阅逻辑数据组和事件监视器输出表。

evm-group

标识要为其定义目标表的逻辑数据组。该值取决于事件监视器的类型，如下表中所示：

事件监视器的类型	evm-group 值
程序包高速缓存	PKGCACHE pkgcache_metrics pkgcache_stmt_args CONTROL

无格式事件表

指定事件监视器的目标是无格式事件表。无格式事件表用于存储收集的程序包高速缓存事件监视器数据。数据以其原始二进制格式存储在直接插入的 BLOB 列中。 BLOB 列可以包含多个不同类型的二进制记录。 BLOB 列中的数据不是可读格式，需要通过使用 db2evmonfmt 基于 Java 的工具， EVMON_FORMAT_UE_TO_XML 表函数或 EVMON_FORMAT_UE_TO_TABLES 过程将其转换为可使用的格式，例如 XML 文档或关系表。

target-table-options

标识目标表的选项。如果未指定 target-table-options 的值，那么将继续执行 CREATE EVENT MONITOR FOR PACKAGE CACHE 处理，如下所示:

将使用派生表名称 (如 TABLE table-name的描述中所述)。
使用与使用 CREATE TABLE 创建没有表空间名称的表时相同的过程来选择缺省表空间。
PCTDEACTIVATE 设置为 100。

表 table-name

指定目标表的名称。目标表必须是非分区表。如果名称未限定，那么表模式缺省为 CURRENT SCHEMA 专用寄存器中的值。如果没有为未格式化的事件表提供名称，那么未限定的名称等于 event-monitor-name，即，未格式化的事件表将在事件监视器之后命名。如果没有为格式化事件表提供名称，那么未限定的名称派生自 evm-group 和 event-monitor-name ，如下所示:

   substring(evm-group CONCAT '_'
     CONCAT event-monitor-name,1,128)

IN tablespace-name

指定要在其中创建表的表空间。 CREATE EVENT MONITOR FOR PACKAGE CACHE 语句不会创建表空间。

如果未提供表空间名称，那么将使用与使用 CREATE TABLE 在没有表空间名称的情况下创建表时相同的进程来选择表空间。

表空间的页面大小会影响使用的 INLINE LOB 长度。请考虑指定具有尽可能大的页面大小的表空间，以提高事件监视器的 INSERT 性能。

PCTDEACTIVATE 整数

如果要在自动存储（非临时）或 DMS 表空间中创建事件监视器的表，那么 PCTDEACTIVATE 参数会指定在自动停用事件监视器之前表空间必须达到的填满程度。指定的值（表示一个百分比）可以介于 0 到 100 之间，其中 100 表示在表空间完全填满时才会停用事件监视器。如果未指定 PCTDEACTIVATE，那么将使用缺省值 100。对于 SMS 表空间，将忽略此选项。

要点: 如果目标表空间启用了自动调整大小，请将 PCTDEACTIVATE 参数设置为 100。或者，完全省略此子句以应用缺省值 100。否则，如果在表空间自动调整大小之前表空间达到 PCTDEACTIVTATE 指定的阈值，那么可能会意外停用事件监视器。

AUTOSTART

指定每当激活用于运行事件监视器的数据库分区时，都会自动激活事件监视器。这是程序包高速缓存事件监视器的缺省行为。

MANUALSTART

指定必须使用 SET EVENT MONITOR STATE 语句手动激活事件监视器。在激活 MANUALSTART 事件监视器后，可以使用 SET EVENT MONITOR STATE 语句或通过停止实例将其取消激活。

注意

如果目标表尚不存在，那么将在执行 CREATE EVENT MONITOR FOR PACKAGE CACHE 语句时创建该表。
在 CREATE EVENT MONITOR FOR PACKAGE CACHE 处理期间，如果发现某个表已定义为供另一个事件监视器使用，那么 CREATE EVENT MONITOR FOR PACKAGE CACHE 语句将失败，并且会将错误传递回应用程序。将定义一个表以供其他事件监视器使用（前提是该表名与在 SYSCAT.EVENTTABLES 目录视图中找到的值匹配）。如果该表存在并且未定义为供另一个事件监视器使用，那么该事件监视器将复用该表。
删除事件监视器不会删除任何表。删除事件监视器后，必须手动删除任何关联的表。
不会自动从此事件监视器创建的无格式事件表或常规表中修剪锁定事件数据。使用 EVMON_FORMAT_UE_TO_TABLES 过程时，可以使用用于从 UE 表中修剪数据的选项。对于写入常规表的事件监视器，必须手动修剪事件数据。
在分区数据库环境中，数据仅写入其表空间所在的成员上的目标表。如果目标表的表空间在成员上不存在，那么不会在该成员上捕获将写入该目标表的事件数据。此行为允许用户通过创建仅存在于某些成员上的表空间来选择要监视的成员子集。
在分区数据库环境中，仅在从数据库程序包高速缓存中逐出条目的成员上将数据写入目标表。
在分区数据库环境中，如果某些目标表不驻留在某个成员上，但其他目标表驻留在该成员上，那么仅记录驻留在该成员上的目标无格式事件表的数据。
FLUSH EVENT MONITOR 语句不适用于此事件监视器，并且对其发出此语句将不起作用。
创建程序包高速缓存事件监视器后，无法更改或改变过滤器和控制选项。要更改过滤器和控制选项，必须取消激活，删除事件监视器，然后使用新的过滤器和控制选项重新创建事件监视器。

使用大表空间实现高吞吐量

事件数据将插入到无格式事件表的内联 BLOB 数据列中。通常， BLOB 数据存储在单独的 LOB 表空间中，因此可能会迂到额外的性能开销。当直接插入到基本表的数据页面中时， BLOB 数据不会迂到此开销。如果 BLOB 数据的大小小于表空间页大小减去记录前缀，那么数据库管理器将自动内联无格式事件表记录的 BLOB 数据部分。因此，为了实现高效率和应用程序吞吐量，建议您在尽可能大的表空间中创建事件监视器，最多包含 32 KB 表空间以及关联的缓冲池。

数据包高速缓存记录的内联: 对于程序包高速缓存事件监视器， stmt_text， comp_env_desc和 section_env 监视元素的大小将确定程序包高速缓存记录是否直接插入。如果这些字段的总数超过表空间大小，那么将不会直接插入记录。
确定 EVENT_DATA 是否直接插入: 使用 ADMIN_IS_INLINED 和 ADMIN_EST_INLINE_LENGTH 函数来确定记录是否内联，并获取所需内联长度的估算值。

限制

在数据库取消激活期间，程序包高速缓存事件监视器不会收集已逐出的条目。

示例

示例 1: 此示例创建名为 CACHEEVMON 的程序包高速缓存事件监视器，该监视器将收集与程序包高速缓存节逐出事件相关的数据并将数据写入表。
```
   CREATE EVENT MONITOR CACHEEVMON
     FOR PACKAGE CACHE
     WRITE TO TABLE 
```
此事件监视器将其输出写入以下表:
- pkgcache_cacheevmon
- pkgcache_metrics_cacheevmon
- pkgcache_stmt_args
- 控制 CACHEEVMON
示例 2: 此示例创建名为 CACHESTMTEVMON 的程序包高速缓存事件监视器，该监视器将收集与程序包高速缓存段逐出事件相关的数据，并将其存储在未格式化的事件表 ALAN.STMTEVENTS中。
```
   CREATE EVENT MONITOR CACHESTMTEVMON
     FOR PACKAGE CACHE
     WRITE TO UNFORMATTED EVENT TABLE (TABLE ALAN.STMTEVENTS)
```
示例 3: 此示例创建名为 CACHESTMTEVMON 的程序包高速缓存事件监视器，该监视器将收集与程序包高速缓存节逐出事件相关的数据，并将其存储在表空间 APPSPACE 中的无格式事件表 ALAN.STMTEVENTS 中。当表空间变满 85% 时，事件监视器将取消激活。
```
   CREATE EVENT MONITOR CACHESTMTEVMON
     FOR PACKAGE CACHE
     WRITE TO UNFORMATTED EVENT TABLE 
        (TABLE ALAN.STMTEVENTS IN APPSPACE PCTDEACTIVATE 85)
```

CREATE EVENT MONITOR（程序包高速缓存）语句

调用

授权

语法

描述

注意

限制

示例