SQL トレース機能によるトレース対象 SQL ステートメントの指定方法：dbms_sql.add_trace の使用手順 - PolarDB

dbms_sql.add_trace は、SQL トレース機能によるオンデマンドの追跡対象として特定の SQL ステートメントを登録するストアドプロシージャです。

前提条件

このプロシージャを呼び出す前に、loose_sql_trace_type パラメーターを DEMAND に設定します。

構文

dbms_sql.add_trace('<schema>', '<query>')

プロシージャ実行後、PolarDB は SQL ステートメント内の定数をテンプレートに正規化します。このテンプレートと一致するステートメントが自動的にトレース対象となります。

パラメーター

パラメーター	説明
`schema`	スキーマ名です。
`query`	実行される SQL ステートメントです。

注意事項

このプロシージャの動作は、実行ノードによって異なります。

プライマリノード：トレース登録は永続化されます。mysql.sql_sharing テーブル内の関連レコードが削除され、すべての読み取り専用ノードへ同期されます。

読み取り専用ノード：トレース登録は永続化されません。このストアドプロシージャは、読み取り専用ノード上でのみ実行可能です。クラスターエンドポイント経由でデータベースにアクセスした場合、テンプレート化された SQL ステートメントは自動的にプライマリノードへルーティングされます。

使用例

この例では、範囲クエリをトレース対象として登録し、その後、システムテーブルを照会してテンプレートおよび実行統計情報を確認します。

ステップ 1：トレース対象となる SQL ステートメントの登録

call dbms_sql.add_trace('test', 'select * from t where c1 > 1 and c1 < 10');

ステップ 2：mysql.sql_sharing におけるトレーステンプレートの確認

mysql.sql_sharing テーブルを照会し、ステートメントが正しく登録・テンプレート化されていることを確認します：

select * from mysql.sql_sharing\G

期待される出力：

*************************** 1. row ***************************
         Id: (id number)
     Sql_id: 82t4dswtqjg02
Schema_name: test
       Type: SQL_TRACE
Digest_text: SELECT * FROM `t` WHERE `c1` > ? AND `c1` < ?
    Plan_id: NULL
       Plan: NULL
    Version: 0
Create_time: 2022-11-07 19:05:27.980605
Update_time: 2022-11-07 19:05:27.980605
 Extra_info: NULL

Digest_text フィールドには正規化されたテンプレートが表示されます：定数値 1 および 10 が ? に置き換えられています。このパターンに一致するすべてのステートメントが、使用される具体的な定数値に関わらず、今後トレース対象となります。

ステップ 3：テンプレートに一致するステートメントの実行

select * from  t where c1 > 1 and c1 < 10;
select * from  t where c1 > 1 and c1 < 100;

ステップ 4：トレースデータおよび実行計画の統計情報の確認

information_schema.sql_sharing を照会し、実行統計および使用された実行計画を確認します：

select * from information_schema.sql_sharing\G

期待される出力：

*************************** 1. row ***************************
              TYPE: SQL
            SQL_ID: 82t4dswtqjg02
       SCHEMA_NAME: test
       DIGEST_TEXT: SELECT * FROM `t` WHERE `c1` > ? AND `c1` < ?
           PLAN_ID: NULL
              PLAN: NULL
        PLAN_EXTRA: NULL
        ERROR_CODE: NULL
            REF_BY: SQL_TRACE(DEMAND)
   FIRST_LOAD_TIME: 2022-11-07 19:05:28
     LAST_HIT_TIME: 2022-11-07 19:17:24
        EXECUTIONS: 2
     SUM_WAIT_TIME: 363
     MIN_WAIT_TIME: 179
     MAX_WAIT_TIME: 184
     SUM_EXEC_TIME: 925
     MIN_EXEC_TIME: 438
     MAX_EXEC_TIME: 487
     SUM_ROWS_SENT: 106
     MIN_ROWS_SENT: 8
     MAX_ROWS_SENT: 98
 SUM_ROWS_EXAMINED: 108
 MIN_ROWS_EXAMINED: 8
 MAX_ROWS_EXAMINED: 100
 SUM_ROWS_AFFECTED: 0
 MIN_ROWS_AFFECTED: 0
 MAX_ROWS_AFFECTED: 0
  SUM_LOGICAL_READ: 122
  MIN_LOGICAL_READ: 19
  MAX_LOGICAL_READ: 103
 SUM_PHY_SYNC_READ: 0
 MIN_PHY_SYNC_READ: 0
 MAX_PHY_SYNC_READ: 0
SUM_PHY_ASYNC_READ: 0
MIN_PHY_ASYNC_READ: 0
MAX_PHY_ASYNC_READ: 0
             EXTRA: {TRACE_ROW_ID:10}
*************************** 2. row ***************************
              TYPE: PLAN
            SQL_ID: 82t4dswtqjg02
       SCHEMA_NAME: test
       DIGEST_TEXT: NULL
           PLAN_ID: 5a4cvp4gjqgfj
              PLAN: /*+ NO_INDEX(`t`@`select#1`) */
        PLAN_EXTRA: {`t`@`select#1`:ALL}
        ERROR_CODE: 0
            REF_BY: SQL_TRACE(DEMAND)
   FIRST_LOAD_TIME: 2022-11-07 19:17:24
     LAST_HIT_TIME: 2022-11-07 19:17:24
        EXECUTIONS: 1
     SUM_WAIT_TIME: 184
     MIN_WAIT_TIME: 184
     MAX_WAIT_TIME: 184
     SUM_EXEC_TIME: 487
     MIN_EXEC_TIME: 487
     MAX_EXEC_TIME: 487
     SUM_ROWS_SENT: 98
     MIN_ROWS_SENT: 98
     MAX_ROWS_SENT: 98
 SUM_ROWS_EXAMINED: 100
 MIN_ROWS_EXAMINED: 100
 MAX_ROWS_EXAMINED: 100
 SUM_ROWS_AFFECTED: 0
 MIN_ROWS_AFFECTED: 0
 MAX_ROWS_AFFECTED: 0
  SUM_LOGICAL_READ: 103
  MIN_LOGICAL_READ: 103
  MAX_LOGICAL_READ: 103
 SUM_PHY_SYNC_READ: 0
 MIN_PHY_SYNC_READ: 0
 MAX_PHY_SYNC_READ: 0
SUM_PHY_ASYNC_READ: 0
MIN_PHY_ASYNC_READ: 0
MAX_PHY_ASYNC_READ: 0
             EXTRA: NULL
*************************** 3. row ***************************
              TYPE: PLAN
            SQL_ID: 82t4dswtqjg02
       SCHEMA_NAME: test
       DIGEST_TEXT: NULL
           PLAN_ID: 463zszw4mbv3w
              PLAN: /*+ INDEX(`t`@`select#1` `i_c1`) */
        PLAN_EXTRA: {`t`@`select#1`:range}
        ERROR_CODE: 0
            REF_BY: SQL_TRACE(DEMAND)
   FIRST_LOAD_TIME: 2022-11-07 19:17:21
     LAST_HIT_TIME: 2022-11-07 19:17:21
        EXECUTIONS: 1
     SUM_WAIT_TIME: 179
     MIN_WAIT_TIME: 179
     MAX_WAIT_TIME: 179
     SUM_EXEC_TIME: 438
     MIN_EXEC_TIME: 438
     MAX_EXEC_TIME: 438
     SUM_ROWS_SENT: 8
     MIN_ROWS_SENT: 8
     MAX_ROWS_SENT: 8
 SUM_ROWS_EXAMINED: 8
 MIN_ROWS_EXAMINED: 8
 MAX_ROWS_EXAMINED: 8
 SUM_ROWS_AFFECTED: 0
 MIN_ROWS_AFFECTED: 0
 MAX_ROWS_AFFECTED: 0
  SUM_LOGICAL_READ: 19
  MIN_LOGICAL_READ: 19
  MAX_LOGICAL_READ: 19
 SUM_PHY_SYNC_READ: 0
 MIN_PHY_SYNC_READ: 0
 MAX_PHY_SYNC_READ: 0
SUM_PHY_ASYNC_READ: 0
MIN_PHY_ASYNC_READ: 0
MAX_PHY_ASYNC_READ: 0
             EXTRA: NULL

出力には、1 行の SQL と 2 行の PLAN が含まれており、いずれも同じ SQL_ID を共有しています。これは、2 回のトレース実行が異なる実行計画を使用したことを意味します：

2 行目（PLAN）：全表スキャン（ALL）、ヒントワード NO_INDEX により識別されます。この計画では 100 行が検査され、実行時間は 487 マイクロ秒でした。
3 行目（PLAN）：インデックス i_c1 を用いた範囲スキャン（range）。この計画では 8 行のみが検査され、実行時間は 438 マイクロ秒でした。

テンプレートに一致する SQL ステートメントは、以下の実行計画に対応します：i_c1 インデックスの範囲スキャンおよび全表スキャンです。