CREATE EVENT MONITOR (阈值违例) 语句

CREATE EVENT MONITOR (阈值违例) 语句定义将记录使用数据库时发生的阈值违例事件的监视器。阈值违例事件监视器的定义还指定数据库应记录事件的位置。

调用

阈值违例事件监视器可以收集有关违反阈值的应用程序的更多信息。添加这些监视元素不会影响现有阈值违例事件监视器，但为了收集其他应用程序信息，必须删除并重新创建现有监视器。

此语句可嵌入应用程序中或者以交互方式发出。它是一个可执行语句，仅当 DYNAMICRULES 运行行为对于程序包有效时才能动态编译 (SQLSTATE 42509)。

授权

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

DBADM 权限
SQLADM 权限

语法

formatted-event-table-info

target-table-options

file-options

Notes:

¹ Each clause can be specified only once.
² Clauses can be separated with a space or a comma.

描述

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

FOR

指示要记录的事件类型。

THRESHOLD VIOLATIONS: 指定事件监视器在违反阈值时记录阈值违例事件。此类事件可以记录在活动生命中的任何时刻，而不仅仅是在完成时。

WRITE TO

指示数据的目标。

表

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

formatted-event-table-info

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

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

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

事件监视器的类型	evm-group 值
阈值违例	THRESHOLDVIOLATIONS CONTROL

target-table-options

标识组的目标表。

TABLE table-name

指定目标表的名称。目标表必须是非分区表。如果此名称为非标准名称，那么表模式缺省设置为 CURRENT SCHEMA 专用寄存器中的值。如果未提供名称，那么将从 evm-group 和 event-monitor-name 派生非标准名称，如下所示：

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

IN 表空间名称

定义要在其中创建表的表空间。如果未提供表空间名称，那么将利用与使用 CREATE TABLE 创建表（不使用表空间名称）时相同的过程来选择表空间。

PCTDEACTIVATE integer

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

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

如果未指定 target-table-options 的值，那么将执行 CREATE EVENT MONITOR 处理，如下所示：

将使用派生的表名。
将选择缺省表空间。
PCTDEACTIVATE 参数缺省设置为 100。

BUFFERSIZE 页面

指定事件监视器缓冲区的大小 (以 4K 页为单位)。表事件监视器插入缓冲区中的所有数据，并在处理缓冲区后发出 COMMIT。缓冲区越大，事件监视器使用的落实作用域越大。高度活动的事件监视器应该具有比相对不活动的事件监视器更大的缓冲区。当监视器启动时，将分配两个具有指定大小的缓冲区。事件监视器使用双重缓冲来允许异步 I/O。

每个缓冲区的缺省大小为 4 页（分配两个 16K 缓冲区）。最小大小为 1 页。由于缓冲区是根据监视器堆进行分配，所以缓冲区的最大大小受该监视器堆大小限制。如果许多事件监视器同时使用，请增大 mon_heap_sz 数据库管理器配置参数的大小。

注: 阈值违例事件监视器不支持此关键字。编译器接受此关键字，但该关键字对事件监视器的行为没有影响。

BLOCKED

指定当代理确定两个事件缓冲区都已满时，生成事件的每个代理都应等待将事件缓冲区写出到磁盘。应选择 BLOCKED 以确保不会丢失任何事件数据。这是缺省选项。

NONBLOCKED

指定如果代理程序确定两个事件缓冲区都已满，那么生成事件的每个代理程序都不应等待将事件缓冲区写出到磁盘。 NONBLOCKED 事件监视器不会将数据库操作减慢到 BLOCKED 事件监视器的范围。但是， NONBLOCKED 事件监视器可能会在高度活动的系统上丢失数据。

注: 阈值违例事件监视器不支持此关键字。编译器接受此关键字，但此关键字对阈值违例事件监视器没有影响。将创建事件监视器，就像指定了 BLOCKED 关键字一样。

PIPE

指定事件监视器数据的目标是命名管道。事件监视器通过单个流将数据写入管道中（就像它是单个无限长的文件一样）。将数据写入管道时，事件监视器不会执行受阻写操作。如果管道缓冲区中没有空间，那么事件监视器将丢弃数据。如果监控应用程序希望确保不会丢失任何数据，那么它应及时读取数据。

pipe-name

事件监视器将向其写入数据的管道 ( AIX®上的 FIFO) 的名称。

管道的命名规则特定于平台。

操作系统	命名规则
AIX	管道名可被视为文件名。因此，允许使用相对管道名称，这些名称可被视为相对路径名称（请参阅 path-name 的描述）。
Linux®	管道名可被视为文件名。因此，允许使用相对管道名称，这些名称可被视为相对路径名称（请参阅 path-name 的描述）。
Windows	由于管道名称采用特殊的语法，因此需要使用绝对管道名称。

在创建事件监视器时，不会检查是否存在管道。监控应用程序应在激活事件监控器时创建并打开一个管道，以便读取数据。如果该管道此时不可用，那么事件监视器将自行关闭，并记录一条错误。（也就是说，如果由于 AUTOSTART 选项而在数据库启动时激活了事件监视器，那么事件监视器将在系统错误日志中记录一条错误。）如果通过 SET EVENT MONITOR STATE SQL 语句激活了事件监视器，那么该语句将失败 (SQLSTATE 58030)。

文件

指示事件监视器数据的目标是一个文件（或一组文件）。事件监视器将数据流写出为一系列 8 字符编号的文件，扩展名为 "evt"。 (例如， 00000000.evt， 00000001.evt和 00000002.evt)。即使数据被分为较小的数据块，也应考虑将数据作为一个逻辑文件（即，数据流的开头是文件 00000000.evt 中的第一个字节；数据流的结尾是文件 nnnnnnnn.evt 的最后一个字节）。

可以定义每个文件的最大大小以及最大文件数。事件监视器永远不会将单个事件记录拆分到两个文件。但是，事件监视器可能会将相关记录写入两个不同的文件中。在处理事件文件时，应用程序应使用这些数据来跟踪此类相关信息。

path-name事件监视器应在其中写入事件文件数据的目录的名称。该路径必须在服务器上已知; 但是，该路径本身可能位于另一数据库分区 (例如， NFS 安装的文件) 上。在指定 path-name 时，必须使用字符串常量。

在 CREATE EVENT MONITOR 时，不一定存在该目录。但是，在激活事件监视器时，会检查是否存在目标路径。此时，如果目标路径不存在，那么将引发错误 (SQLSTATE 428A3)。

如果指定了绝对路径，那么将使用指定的路径。

在除 Db2 pureScale® 以外的环境中，如果指定了相对路径（不是以根目录开始的路径），则将使用数据库目录中 DB2EVENT 目录的相对路径。

在 Db2® pureScale 环境中，如果指定了相对路径，则将使用数据库目录中数据库所有者目录的相对路径。

可以指定两个或更多个具有相同目标路径的事件监视器。但是，首次激活其中一个事件监视器后，只要目标目录不为空，就无法激活任何其他事件监视器。

file-options

指定文件格式选项。

MAXFILES NONE

指定事件监视器可创建的事件文件数没有限制。这是缺省值。

MAXFILES number-of-files

指定特定事件监视器任何时候存在的事件监视器文件数存在限制。每当事件监视器必须创建其他文件时，它都会执行检查以确保目录中的 .evt 文件数小于 number-of-files。如果达到了此限制，那么事件监视器将自行关闭。

如果应用程序在写入事件文件后从目录中移除了这些文件，那么事件监视器可以生成的文件总数可能会超过 number-of-files。提供的此选项允许用户保证事件数据所用的空间不会超过指定的磁盘空间量。

MAXFILESIZE pages

指定每个事件监视器文件的大小存在限制。每当事件监视器将新的事件记录写入文件时，它都会执行检查以确保该文件不会增长到超过 pages（以 4K 页面为单位）。如果生成的文件过大，那么事件监视器会切换到下一个文件。此选项的缺省值为：

Linux -1000 4K 页面
UNIX-1000 4K 页面
Windows-200 4K 页

此页数必须至少大于事件缓冲区的大小（以页为单位）。如果不满足此要求，那么将引发错误 (SQLSTATE 428A4)。

MAXFILESIZE NONE

指定未设置文件大小限制。如果指定了 MAXFILESIZE NONE，那么还必须指定 MAXFILES 1。此选项意味着一个文件将包含特定事件监视器的所有事件数据。在这种情况下，唯一的事件文件为 00000000.evt。

BUFFERSIZE 页面

指定事件监视器缓冲区的大小 (以 4K 页为单位)。将缓冲所有事件监视器文件 I/O 以提高事件监视器的性能。缓冲区越大，事件监视器执行的 I/O 将越少。高度活动的事件监视器应该具有比相对不活动的事件监视器更大的缓冲区。当监视器启动时，将分配两个具有指定大小的缓冲区。事件监视器使用双重缓冲来允许异步 I/O。

每个缓冲区的缺省大小为 4 页（分配两个 16K 缓冲区）。最小大小为 1 页。缓冲区的最大大小受 MAXFILESIZE 参数的值以及监视器堆的大小限制，因为缓冲区是从该堆分配的。如果许多事件监视器同时使用，请增大 mon_heap_sz 数据库管理器配置参数的大小。

将其数据写入管道的事件监视器还具有两个大小各为 1 页的内部 (不可配置) 缓冲区。这些缓冲区也是从监视器堆 (MON_HEAP) 分配的。对于具有管道目标的每个活动事件监视器，请将数据库堆的大小增大 2 页。

注: 阈值违例事件监视器不支持此关键字。编译器接受此关键字，但该关键字对事件监视器的行为没有影响。

BLOCKED

NONBLOCKED

APPEND

指定如果在打开事件监视器时事件数据文件已经存在，那么事件监视器会将新的事件数据附加到现有数据文件流中。当重新激活事件监视器时，它将继续写入事件文件，就像它从未关闭过一样。 APPEND 是缺省选项。

如果在新创建的事件监视器要将其事件数据写入到的目录中存在现有事件数据，那么 APPEND 选项在 CREATE EVENT MONITOR 时不适用。

REPLACE

指定如果在打开事件监视器时事件数据文件已存在，那么事件监视器将擦除所有事件文件并开始将数据写入文件 00000000.evt。

MANUALSTART

指定必须使用 SET EVENT MONITOR STATE 语句手动激活事件监视器。在激活 MANUALSTART 事件监视器后，只能使用 SET EVENT MONITOR STATE 语句或通过停止实例来停用该事件监视器。

AUTOSTART

指定每当激活用于运行事件监视器的数据库分区时，都会自动激活事件监视器。这是阈值违例事件监视器的缺省行为。

ON MEMBER member-number

指定要运行文件或管道事件监视器的成员。当监视作用域定义为 LOCAL 时，仅在成员上收集数据。 I/O 组件将以物理方式在指定的成员上运行，将记录写入指定的文件或管道。

启用Db2 pureScale时，默认值为-1。

如果值为-1，则允许 I/O 组件从任何活动成员运行。此外，如果 I/O 组件不再能够在给定的成员上运行，那么将在另一个可用的活动成员上运行 I/O 组件时重新启动事件监视器。

此子句对表事件监视器无效。在分区数据库环境中，write-to-table 事件监视器将在定义了目标表的表空间的所有数据库分区上运行和写入事件。

在 Db2 pureScale 环境中， "写入表" 事件监视器将记录所有活动成员上的事件。

如果未指定此子句并且未启用 Db2 pureScale，那么将使用当前已连接的成员。

如果未指定此子句，并且已启用 Db2 pureScale ，那么 I/O 组件能够在任何当前连接的成员上运行。

LOCAL

事件监视器仅报告正在运行的成员。它提供了数据库活动的部分跟踪。这是缺省值。

此子句对文件或管道监视器有效。它对表事件监视器无效。

对于此类型的事件监视器，GLOBAL 不是有效的作用域。

规则

THRESHOLD VIOLATIONS 事件类型不能与特定事件监视器定义中的任何其他事件类型组合在一起。

注意

事件监视器定义都记录在 SYSCAT.EVENTMONITORS 目录视图中。事件本身都记录在 SYSCAT.EVENTS 目录视图中。目标表的名称都记录在 SYSCAT.EVENTTABLES 目录视图中。
如果要运行事件监视器的成员未处于活动状态，那么在该成员下次激活时将发生事件监视器激活。
在激活事件监视器后，它的行为类似于自动启动事件监视器，直到显式停用该事件监视器或回收该实例。即，如果在取消激活成员时事件监视器处于活动状态，并且随后重新激活了该成员，那么还将显式重新激活事件监视器。

写入表事件监视器：一般注意事项：

所有目标表都是在执行 CREATE EVENT MONITOR 语句时创建的。
如果由于任何原因而导致创建表失败，那么会将一个错误传递回应用程序，并且 CREATE EVENT MONITOR 语句将失败。
目标表只能由一个事件监视器使用。在 CREATE EVENT MONITOR 处理期间，如果发现已定义目标表以供其他事件监视器使用，那么 CREATE EVENT MONITOR 语句将失败，并将一条错误传递回应用程序。将定义一个表以供其他事件监视器使用（前提是该表名与在 SYSCAT.EVENTTABLES 目录视图中找到的值匹配）。
在 CREATE EVENT MONITOR 处理期间，如果表已存在但未定义为可供其他事件监视器使用，那么将不会创建表，并会继续执行处理。系统将一条警告传递回应用程序。
在执行 CREATE EVENT MONITOR 语句之前，必须存在表空间。 CREATE EVENT MONITOR 语句不会创建表空间。
如果指定了此项，那么将忽略 LOCAL 和 GLOBAL 关键字。通过 WRITE TO TABLE 事件监视器，将在实例中的每个成员上启动事件监视器输出进程或线程，并且这些进程中的每个进程仅报告其运行所在的成员的数据。
平面监视器日志文件或管道格式中的以下事件类型不会通过写操作记录到表事件监视器：
- LOG_STREAM_HEADER
- LOG_HEADER
- DB_HEADER (未记录元素 db_name 和 db_path。元素 conn_time 记录在 CONTROL 中。)
在分区数据库环境中，仅将数据写入到已存在表空间的数据库分区上的目标表中。如果某个数据库分区上不存在目标表的表空间，那么将忽略该目标表的数据。此行为允许用户通过创建仅存在于某些数据库分区上的表空间来选择监视一部分数据库分区。
在 Db2 pureScale 环境中，将从每个成员写入数据。

在分区数据库环境中，如果某些目标表不驻留在数据库分区上，但其他目标表确实驻留在同一数据库分区上，那么将仅记录驻留在该数据库分区上的目标表的数据。
用户必须手动修剪所有目标表。

表列：

表中的列名与事件监视器元素标识匹配。将忽略没有相应目标表列的事件监视元素。
使用 db2evtbl 命令来构建 CREATE EVENT MONITOR 命令，该命令包含组的完整元素列表。

用于监视元素的列类型与以下映射相关：

SQLM_TYPE_STRING                     CHAR[n], VARCHAR[n] or CLOB(n)
                                     (If the data in the event monitor
                                     record exceeds n bytes,
                                     it is truncated.)
SQLM_TYPE_U8BIT and SQLM_TYPE_8BIT   SMALLINT, INTEGER or BIGINT
SQLM_TYPE_16BIT and SQLM_TYPE_U16BIT SMALLINT, INTEGER or BIGINT
SQLM_TYPE_32BIT and SQLM_TYPE_U32BIT INTEGER or BIGINT
SQLM_TYPE_U64BIT and SQLM_TYPE_64BIT BIGINT
sqlm_timestamp                       TIMESTAMP
sqlm_time(elapsed time)              BIGINT
sqlca:
  sqlerrmc                           VARCHAR[72]
  sqlstate                           CHAR[5]
  sqlwarn                            CHAR[11]
  other fields                       INTEGER or BIGINT

列定义为 NOT NULL。

与其他目标表不同，CONTROL 表中的列与监视器元素标识不匹配。列定义如下：

列名	数据类型	是否可空	描述
PARTITION_KEY	INTEGER	N	分发键（仅限分区数据库）
PARTITION_NUMBER	INTEGER	N	数据库分区号（仅限分区数据库）
EVMONNAME	VARCHAR(128)	N	事件监视器的名称
消息	VARCHAR(128)	N	描述 MESSAGE_TIME 列的性质。有关更多详细信息，请参阅消息-"控制表消息" 监视元素
MESSAGE_TIME	TIMESTAMP	N	时间戳记

在分区数据库环境中，每个表的第一列命名为 PARTITION_KEY，此列不为空且为 INTEGER 类型。此列将用作表的分发键。此列的值将被选中，以便每个事件监视器进程将数据插入到运行该进程的数据库分区中；即，插入操作将在运行事件监视器进程的数据库分区本地执行。在任何数据库分区上，PARTITION_KEY 字段将包含相同的值。这意味着，如果删除了某个数据库分区并重新分布了数据，那么所删除的数据库分区上的所有数据都将转到另一个数据库分区上，而不是均匀分布。因此，在移除数据库分区之前，请考虑删除该数据库分区上的所有表行。
在分区数据库环境中，可以为每个表定义一个名为 PARTITION_NUMBER 的列。此列为 NOT NULL 且为 INTEGER 类型。它包含要插入数据的数据库分区的编号。与 PARTITION_KEY 列不同，PARTITION_NUMBER 列不是强制性的。在非分区数据库环境中不允许使用 PARTITION_NUMBER 列。

表属性：

将使用缺省表属性。除了分布键（仅限分区数据库）外，在创建表时不会再指定额外的选项。
可以创建表索引。
可以添加额外的表属性（例如 volatile、RI、触发器、约束等），但事件监视器进程（或线程）将忽略这些属性。
如果添加“not logged initially”作为表属性，那么在第一次 COMMIT 时会关闭该进程，并且不会重新打开该进程。

事件监视器激活：

当激活事件监视器时，将从 SYSCAT.EVENTTABLES 目录视图中检索所有目标表名称。
在分区数据库环境中，将在实例的每个数据库分区上执行激活处理。在特定数据库分区上，激活处理确定每个目标表的表空间和数据库分区组。仅当数据库分区上至少存在一个目标表时，才会在该数据库分区上激活事件监视器。此外，如果在数据库分区上未找到某个目标表，那么将标记该目标表，以便在运行时处理期间删除发往该表的数据。
如果在激活事件监视器时不存在目标表（如果表空间不驻留在数据库分区上，则在分区数据库环境中），那么将继续激活，否则将忽略已插入到该表中的数据。
激活处理将验证每个目标表。如果验证失败，那么事件监视器的激活将失败，并且会将相关消息写入管理日志中。
在分区数据库环境中激活期间，FIRST_CONNECT 和 EVMON_START 的 CONTROL 表行仅插入到目录数据库分区中。这要求控制表的表空间存在于目录数据库分区上。如果它不存在于目录数据库分区上，那么将不执行这些插入操作。
在分区数据库环境中，如果在激活 "写入表" 事件监视器时分区尚未处于活动状态，那么将在下次激活该分区时激活事件监视器。

运行时间：

使用 DATAACCESS 权限运行事件监视器。
如果事件监视器处于活动状态，那么对目标表的插入操作将失败：
- 将回滚未落实的更改。
- 系统会将一条消息写入到管理日志。
- 已停用事件监视器。
如果事件监视器处于活动状态，那么它在处理完事件监视器缓冲区时将执行本地 COMMIT。
在分区数据库或 Db2 pureScale 环境以外的环境中，当最后一个应用程序终止 (并且尚未显式激活数据库) 时，将取消激活所有对表事件监视器的写操作。
在 Db2 pureScale 环境中，当成员停止时，将在给定的成员上取消激活写入表事件监视器，当成员重新启动时，将重新激活写入表事件监视器。

在分区数据库环境中，将在停用目录分区时停用对表事件监视器的写操作。
DROP EVENT MONITOR 语句不会删除目标表。
每当激活对表事件监视器的写操作时，它将获取每个目标表的 IN 表锁，以防止在事件监视器处于活动状态时修改这些表。在事件监视器处于活动状态时会维护所有表上的表锁定。如果需要对任何目标表进行独占访问（例如，当运行实用程序时），请先停用事件监视器以释放表锁，然后再尝试此类访问。

语法替代方法: 为了与先前版本的 Db2 兼容，支持以下语法替代方法以及其他数据库产品。这些备用项是非标准的，不应使用。
- 可以指定 DBPARTITIONNUM 或 NODE 来代替 MEMBER，除非 DB2_ENFORCE_MEMBER_SYNTAX 注册表变量设置为 ON。
- 逗号可用于分隔 target-table-options 子句中的多个选项

示例

定义名为 DBTHRESHOLDVIOLATIONS 的阈值违例事件监视器

   CREATE EVENT MONITOR DBTHRESHOLDVIOLATIONS
       FOR THRESHOLD VIOLATIONS
       WRITE TO TABLE
       THRESHOLDVIOLATIONS (TABLE THRESHOLDVIOLATIONS_DBTHRESHOLDVIOLATIONS
                            IN USERSPACE1
                            PCTDEACTIVATE 100),
       CONTROL (TABLE CONTROL_DBTHRESHOLDVIOLATIONS
                IN USERSPACE1
                PCTDEACTIVATE 100)
       AUTOSTART;