OceanBase 数据库的全链路诊断机制通过建立事务与 SQL 追踪的标准数据模型，扩展了 SQL Trace 的功能，可以提升定位 OBServer 全链路问题的效率，并实现了分布式和并行执行时的追踪分析能力。

运维人员可根据需要使用 PL 程序包  DBMS_MONITOR 中的相关方法来控制应用程序中不同标识信息维度的全链路诊断 Trace 的开启与关闭，以及该 Trace 的打点和相关信息打印到 Trace 日志的策略。需要注意的是，日志打印会根据采样频率判断是否会被采样并记录到内存中，即是否打印到 Trace 日志中具有一定的概率性。

PL 程序包  DBMS_APPLICATION_INFO （设置模块名称、处理过程名称和其他客户端相关信息） 和  DBMS_SESSION （设置 Session Identifier）可以用于在应用程序 APP 中设置标识应用信息。Session Identifier、模块名称、处理过程名称和其他客户端相关信息设置完成后，OBServer 内部会同步设置到当前 Session 的结构信息中，相关信息用户可以通过  V$SESSION 视图查询。

打开和关闭 Trace

OceanBase 数据库通过 PL 程序包  DBMS_MONITOR 控制不同级别的 Trace 收集，以应对所运行的生产环境中不同场景下的诊断需求。

DBMS_MONITOR 程序包所涉及到的相关变量如下：

• session_id：Session ID，可以通过  SHOW PROCESSLIST 命令（仅 MySQL 模式支持）、 GV$OB_PROCESSLIST 等视图查询。

• client_id：Session 的标志符，可以通过  GV$OB_PROCESSLIST 视图的  ID 字段查询

• module_name：Session 的 Module 标记名称，可以通过  GV$OB_PROCESSLIST 视图的  module 字段查询。

• action_name：Session 的 Action 标记名称，可以通过  GV$OB_PROCESSLIST 视图的  action 字段查询。

• tenant_name：租户名称，可选项为空值（非 Null 表示当前租户）和各租户名称。

• level：打印日志的粒度。目前支持三个粒度等级，其中 Level1 为模块级别的粗粒度，Level3 的粒度最精细。

• sample_pct：控制采样频率，取值范围为 [0,1]。

• record_policy: 日志打印策略，即 Trace 信息输出到日志文件中策略。当前支持以下三种策略：

  • ALL：所有 Span 和 Tag 信息均打印到日志文件中, 并且是在每个 Span 结束时就打印到日志文件中。

  • ONLY_SLOW_QUERY：当前请求为 Slow Query，则该部分信息的 Span 和 Tag 会打印到日志文件中。

  • SAMPLE_AND_SLOW_QUERY：当前请求为 Slow Query，则该部分信息的 Span 和 Tag 会打印到日志文件中，其他请求信息的 Span 和 Tag 有一定的概率会打印到日志文件中。

开启和关闭 Session 级别的 Trace

DBMS_MONITOR 包的  OB_SESSION_TRACE_ENABLE 过程根据 Session ID 开启指定 Session 的 Trace。语法如下：

DBMS_MONITOR.OB_SESSION_TRACE_ENABLE(
    session_id      IN  BINARY_INTEGER DEFAULT NULL,
    level           IN  INT,
    sample_pct      IN  NUMBER,
    record_policy   IN VARCHAR2);

说明

如果  session_id 为  NULL，表示当前 Session。

示例：记录当前 Session 相关耗时等信息，采样频率为 50%，并且只记录 Slow Query。

CALL DBMS_MONITOR.OB_SESSION_TRACE_ENABLE(null,1,0.5,'ONLY_SLOW_QUERY');

DBMS_MONITOR 包的  OB_SESSION_TRACE_DISABLE 过程根据 Session ID 关闭指定 Session 的 Trace。语法如下：

DBMS_MONITOR.OB_SESSION_TRACE_DISABLE(session_id  IN  BINARY_INTEGER);

说明

如果  session_id 为  NULL，表示当前 Session。

示例：关闭当前 Session 的 Trace。

CALL DBMS_MONITOR.OB_SESSION_TRACE_DISABLE(null);

开启和关闭 Client Identifier 级别的 Trace

在开启 Session Identifier 级别的 Trace 前需要先使用  DBMS_SESSION 包设置  client_id 标识信息。语法如下：

DBMS_SESSION.SET_IDENTIFIER(client_id VARCHAR2);

DBMS_MONITOR 包的  OB_CLIENT_ID_TRACE_ENABLE 过程可以根据所设置的  client_id 打开指定 Trace。语法如下：

DBMS_MONITOR.OB_CLIENT_ID_TRACE_ENABLE(
    client_id      IN  VARCHAR2,
    level          IN  INT,
    sample_pct     IN  NUMBER,
    record_policy  IN VARCHAR2);

示例：记录  client_id 为  jdbc 的相关耗时等信息，采样频率为 50%，并且只记录 Slow Query。

CALL DBMS_MONITOR.OB_CLIENT_ID_TRACE_ENABLE('jdbc',1,0.5,'ONLY_SLOW_QUERY');

DBMS_MONITOR 包的  OB_CLIENT_ID_TRACE_DISABLE 过程可以根据  client_id 关闭指定 Trace。语法如下：

DBMS_MONITOR.OB_CLIENT_ID_TRACE_DISABLE(client_id IN  VARCHAR2);

示例：关闭  client_id 为  jdbc 的 Trace。

CALL DBMS_MONITOR.OB_CLIENT_ID_TRACE_DISABLE('jdbc');

开启和关闭 Module/Action 级别的 Trace

在开启 Module 或 Action 级别的 Trace 前需要先使用  DBMS_APPLICATION_INFO 包的子程序设置模块名称、处理过程名称和其他客户端相关信息。相关子程序如下：

• SET_MODULE 过程用于设置 APP 中模块的名称。语法如下：

  DBMS_APPLICATION_INFO.SET_MODULE (module_name IN VARCHAR2, action_name IN VARCHAR2);

• SET_ACTION 过程用于设置 APP 模块中某个处理过程的名称。语法如下：

  DBMS_APPLICATION_INFO.SET_ACTION (action_name IN VARCHAR2);

• SET_CLIENT_INFO 过程用于设置其他客户端相关信息。

  DBMS_APPLICATION_INFO.SET_CLIENT_INFO (client_info IN VARCHAR2);

DBMS_MONITOR 包的  OB_MOD_ACT_TRACE_ENABLE 过程可以根据所设置的  module_name 和  action_name 开启指定 Module 或者 Action 的 Trace。语法如下：

DBMS_MONITOR.OB_MOD_ACT_TRACE_ENABLE(
   module_name     IN VARCHAR2 DEFAULT ANY_MODULE,
   action_name     IN VARCHAR2 DEFAULT ANY_ACTION,
   level           IN  INT,
   sample_pct      IN  NUMBER,
   record_policy   IN VARCHAR2);

示例：记录  module_name 为  backup， action_name 为  insert 的相关耗时等信息，采样频率为 50%，并且只记录 Slow Query。

CALL DBMS_APPLICATION_INFO.SET_MODULE('backup','insert');
CALL DBMS_MONITOR.OB_MOD_ACT_TRACE_ENABLE('backup','insert',1,0.5,'ONLY_SLOW_QUERY');

DBMS_MONITOR 包的  OB_MOD_ACT_TRACE_DISABLE 过程可以根据所设置的  module_name 和  action_name 关闭指定 Module 或者 Action 的 Trace。语法如下：

DBMS_MONITOR.OB_MOD_ACT_TRACE_DISABLE(
    module_name     IN  VARCHAR2,
    action_name     IN  VARCHAR2 DEFAULT ALL_ACTIONS);

示例：关闭  module_name 为  backup， action_name 为  insert 的 Trace。

CALL DBMS_MONITOR.OB_MOD_ACT_TRACE_DISABLE('backup','insert');

开启和关闭租户级别的 Trace

DBMS_MONITOR 包的  OB_TENANT_TRACE_ENABLE 过程可以开启当前租户的 Trace。语法如下：

DBMS_MONITOR.OB_TENANT_TRACE_ENABLE(
   level        IN  INT,
   sample_pct   IN  NUMBER,
   record_policy IN VARCHAR2);

示例：记录当前租户中的耗时等信息，全部记录并全部打印。

CALL DBMS_MONITOR.OB_TENANT_TRACE_ENABLE(1, 1, 'ALL');

相关日志信息输出到 trace.log，具体内容示例如下：

[20xx-0x-xx 00:07:46.027232] [1751][T1_TNT_L0][T1][YB42AC12050D-0005E42565DA44B2-0-0] {"trace_id":"0005e495-f920-5adc-7cd1-3730afa11dbd","name":"sql_execute","id":"0005e426-2c2b-0755-0000-000000000005","start_ts":1658707664460666,"end_ts":1658707666027098,"parent_id":"0005e426-3355-05b6-0000-000000000002","is_follow":false}
[20xx-0x-xx 00:07:46.027234] [1751][T1_TNT_L0][T1][YB42AC12050D-0005E42565DA44B2-0-0] {"trace_id":"0005e495-f920-5adc-7cd1-3730afa11dbd","name":"pc_get_plan","id":"0005e426-5aac-d38c-0000-000000000004","start_ts":1658707664460552,"end_ts":1658707664460660,"parent_id":"0005e426-a22f-6cd4-0000-000000000003","is_follow":false}

DBMS_MONITOR 包的  OB_TENANT_TRACE_DISABLE 过程可以关闭指定租户的 Trace。语法如下：

DBMS_MONITOR.OB_TENANT_TRACE_DISABLE(tenant_name  IN VARCHAR2 DEFAULT NULL);

说明

系统租户可以关闭任意租户的 Trace；普通租户只能关闭本租户的 Trace。

示例 1：关闭租户名为  ORACLE 的 Trace。

CALL DBMS_MONITOR.OB_TENANT_TRACE_DISABLE('ORACLE');

示例 2：关闭当前租户的 Trace。

CALL DBMS_MONITOR.OB_TENANT_TRACE_DISABLE();