2026年5月17日の情報です

1. はじめに

前回記事「ADB-S 26ai で 10046/10053 イベントトレースは取れるのか」では、DBMS_MONITOR を使った 2 ステップ回避策で待機イベントつきトレースが取れることを確認しました。
今回はその続編として、Oracle Autonomous Database Serverless（以下 ADB-S）上の Oracle AI Database 26ai で正式追加された DBMS_USERDIAG パッケージ¹ を実機で検証します。このパッケージは「クラウド PDB 環境向けの公式診断手段」として設計されたものです。

今回の検証ゴール

#	検証項目
1	`DBMS_USERDIAG.ENABLE_SQL_TRACE_EVENT` が ADB 26ai で動作し、SESSION_CLOUD_TRACE にトレースが書き出されるか
2	`CHECK_SQL_TRACE_EVENT` でトレースの有効/無効を確認できるか
3	Object Storage に標準フォーマット（.trc）で出力され、既存のトレース解析ツールで利用できるか

結論の先出し

DBMS_USERDIAG は ADB 26ai に存在し、ADMIN ユーザーは EXECUTE 権限を持つ ✅
CHECK_SQL_TRACE_EVENT は 0（無効）/ 非 0（有効）でトレース状態を確認できる。waits=>1 指定時の実測値は 28 ✅
CHECK(0) → ENABLE → CHECK(28) → TRACE マーカー → SQL → DISABLE → CHECK(0) の手順でトレースを制御可能 ✅
SESSION_CLOUD_TRACE に WAIT / STAT / BINDS 各行が書き出される（2 SQL で 2,693 行）✅
Object Storage にオンプレミスと同一フォーマットの .trc ファイルが自動出力され、tkprof 等の既存ツールがそのまま使える ✅
DBMS_MONITOR 2 ステップ法との違いは §6 の比較表を参照

2. 検証環境

項目	内容
ADB-S インスタンス	adbtest02
データベースバージョン	Oracle AI Database 26ai EE 23.26.2.1.0
DEFAULT_LOGGING_BUCKET	設定済み（OCI Object Storage）

SESSION_CLOUD_TRACE にトレースを書き出すには DEFAULT_LOGGING_BUCKET と DEFAULT_CREDENTIAL の事前設定が必要です。未設定の場合は Autonomous AI Database でのアプリケーション・トレースの実行を参照してください。

3. DBMS_USERDIAG パッケージの仕様

3.1. パッケージの存在確認

まず ADB 26ai 上に DBMS_USERDIAG が存在するかを確認します。

SELECT object_name, object_type, status
  FROM all_objects
 WHERE object_name = 'DBMS_USERDIAG';

実行結果:

OBJECT_NAME      OBJECT_TYPE  STATUS
---------------- ------------ ------
DBMS_USERDIAG    PACKAGE      VALID
DBMS_USERDIAG    SYNONYM      VALID

PACKAGE と SYNONYM の両方が VALID であることを確認できました。

3.2. プロシージャ一覧

SELECT procedure_name
  FROM all_procedures
 WHERE object_name = 'DBMS_USERDIAG'
 ORDER BY procedure_name;

プロシージャ	用途
`ENABLE_SQL_TRACE_EVENT`	SQL トレースイベントの有効化・無効化
`CHECK_SQL_TRACE_EVENT`	現在のトレースレベルを確認
`TRACE`	トレースファイルにマーカーメッセージを書き込む
`SET_TRACEFILE_IDENTIFIER`	トレースファイルに識別子を付与
`GET_CALL_STATUS`	直前の DBMS_USERDIAG 呼び出し結果を取得（0=成功、実測値）
`GET_CALL_ERROR_MSG`	直前の呼び出しエラーメッセージを取得
`SET_EXCEPTION_MODE`	エラー時に例外を発生させるか無視するかを設定

3.3. ENABLE_SQL_TRACE_EVENT のシグネチャ

SELECT argument_name, position, data_type, in_out, defaulted
  FROM all_arguments
 WHERE object_name  = 'ENABLE_SQL_TRACE_EVENT'
   AND package_name = 'DBMS_USERDIAG'
 ORDER BY position;

パラメータ	型	デフォルト	説明
`level`	BINARY_INTEGER	Y	10046 レベル相当（と想定）
`sid`	BINARY_INTEGER	Y	ターゲットセッション ID
`ser`	BINARY_INTEGER	Y	ターゲットシリアル番号
`binds`	BINARY_INTEGER	Y	非 0 でバインド変数をトレース（レベル 4 相当と考えられます）
`waits`	BINARY_INTEGER	Y	非 0 で待機イベントをトレース（レベル 8 相当と考えられます）
`plan_stat`	VARCHAR2	Y	`FIRST_EXECUTION`(デフォルト) / `ALL_EXECUTIONS` / `NEVER` / `ADAPTIVE`
`sql_id`	VARCHAR2	Y	特定 SQL_ID に絞ってトレース
`disable`	BINARY_INTEGER	Y	非 0 でトレース無効化
`sys`	BINARY_INTEGER	Y	詳細は公式ドキュメント未掲載

3.4. CHECK_SQL_TRACE_EVENT のシグネチャ

SELECT argument_name, position, data_type, in_out, defaulted
  FROM all_arguments
 WHERE object_name  = 'CHECK_SQL_TRACE_EVENT'
   AND package_name = 'DBMS_USERDIAG'
 ORDER BY position;

パラメータ	型	IN/OUT	説明
`level`	BINARY_INTEGER	OUT	現在有効なトレースレベル（0 または NULL = 無効）
`sql_id`	VARCHAR2	IN	現時点では無視される（公式ドキュメント記載）
`sys`	BINARY_INTEGER	IN	現時点では無視される（公式ドキュメント記載）

3.5. EXECUTE 権限

SELECT grantee, privilege
  FROM all_tab_privs
 WHERE table_name = 'DBMS_USERDIAG';

GRANTEE	PRIVILEGE
PDB_DBA	EXECUTE
ADMIN	EXECUTE

デフォルトでは ADMIN ユーザーには直接 EXECUTE 権限が付与されています。一般ユーザーで実行する場合は ADMIN から GRANT EXECUTE ON DBMS_USERDIAG TO <ユーザー名>; を実行してください。

4. 実際に使ってみる

4.1. 手順の全体像

CHECK（有効前確認）
  ↓
SET_TRACEFILE_IDENTIFIER（識別子付与）
  ↓
ENABLE_SQL_TRACE_EVENT（トレース有効化）
  ↓
CHECK（有効確認）
  ↓
TRACE（マーカー埋め込み） → SQL 実行 → TRACE（マーカー埋め込み）
  ↓
ENABLE_SQL_TRACE_EVENT(disable=>1)（トレース無効化）
  ↓
CHECK（無効確認）
  ↓
SESSION_CLOUD_TRACE を参照

4.2. ステップごとの実行

DBMS_OUTPUT.PUT_LINE の出力を受け取るため、事前に SET SERVEROUTPUT ON; を実行してください。以下の手順は SQL Developer での実行を想定しています。

Step 1: 有効前の状態を確認

DECLARE
  l_level BINARY_INTEGER;
BEGIN
  DBMS_USERDIAG.CHECK_SQL_TRACE_EVENT(level => l_level);
  DBMS_OUTPUT.PUT_LINE('Trace level (before): ' || NVL(TO_CHAR(l_level), 'NULL'));
END;
/

実行結果:

Trace level (before): 0

Step 2: トレースファイルに識別子を付与（任意）

BEGIN
  DBMS_USERDIAG.SET_TRACEFILE_IDENTIFIER('userdiag_test');
END;
/

Step 3: トレースを有効化

BEGIN
  DBMS_USERDIAG.ENABLE_SQL_TRACE_EVENT(
    waits     => 1,                 -- 待機イベントを取得
    binds     => 1,                 -- バインド変数を取得
    plan_stat => 'ALL_EXECUTIONS'   -- 実行のたびに STAT 行を出力
  );
END;
/

Step 4: 有効後の状態を確認

DECLARE
  l_level BINARY_INTEGER;
BEGIN
  DBMS_USERDIAG.CHECK_SQL_TRACE_EVENT(level => l_level);
  DBMS_OUTPUT.PUT_LINE('Trace level (after enable): ' || NVL(TO_CHAR(l_level), 'NULL'));
END;
/

実行結果:

Trace level (after enable):  28

返り値 28 は waits=>1 を指定したときの実測値です。binds=>1 や plan_stat=>'ALL_EXECUTIONS' を追加しても同じく 28 が返ることを確認しており、これらのパラメータは CHECK の返り値に影響しません。

ビット構成を分解すると 28 = 4 + 8 + 16 となります。内部ビット定義は公式ドキュメントに記載されていませんが、従来の 10046 イベントのレベル体系（4=Binds、8=Waits、16=plan_stat）と類似した構造と考えられます。

ビット値（推測）	10046 レベルでの対応	DBMS_USERDIAG パラメータ
4	Binds（バインド変数取得）	`binds`
8	Waits（待機イベント取得）	`waits`
16	plan_stat（実行計画統計）	`plan_stat`

waits=>1 のみでも 28 が返ることから、plan_stat のデフォルト（FIRST_EXECUTION）と基本トレースに相当するビットが常時含まれている可能性があります。

CHECK_SQL_TRACE_EVENT の実用的な使い方は、0 ならトレース無効、非 0 ならトレース有効という判定です。

操作	CHECK の返り値
トレース無効時	0
`ENABLE_SQL_TRACE_EVENT(waits=>1)` 後	28（実測値）
`ENABLE_SQL_TRACE_EVENT(disable=>1)` 後	0

Step 5: TRACE マーカーを挟みながら SQL を実行

TRACE プロシージャを使うと SESSION_CLOUD_TRACE 上に任意の文字列行を挿入できます。
複数の SQL を順番に実行するときのセクション区切りとして便利です。

-- マーカー: SQL-A 開始
BEGIN
  DBMS_USERDIAG.TRACE('=== SQL-A START ===');
END;
/

-- SQL-A: フルスキャン系
SELECT /*+ NO_RESULT_CACHE */
       object_type,
       COUNT(*) AS cnt
  FROM all_objects
 WHERE object_type IN ('TABLE', 'INDEX', 'VIEW')
 GROUP BY object_type
 ORDER BY cnt DESC;

SQL-A の実行結果:

OBJECT_TYPE    CNT
----------- ------
VIEW          9594
INDEX         6429
TABLE         3896

BEGIN
  DBMS_USERDIAG.TRACE('=== SQL-A END / SQL-B START ===');
END;
/

-- SQL-B: バインド変数あり
VARIABLE v_type VARCHAR2(30)
EXEC :v_type := 'TABLE'

SELECT /*+ NO_RESULT_CACHE */ COUNT(*)
  FROM all_objects
 WHERE object_type = :v_type;

BEGIN
  DBMS_USERDIAG.TRACE('=== SQL-B END ===');
END;
/

SQL-B の実行結果:

  COUNT(*)
----------
      3896

Step 6: トレースを無効化して確認

BEGIN
  DBMS_USERDIAG.ENABLE_SQL_TRACE_EVENT(disable => 1);
END;
/

DECLARE
  l_level BINARY_INTEGER;
BEGIN
  DBMS_USERDIAG.CHECK_SQL_TRACE_EVENT(level => l_level);
  DBMS_OUTPUT.PUT_LINE('Trace level (after disable): ' || NVL(TO_CHAR(l_level), 'NULL'));
END;
/

実行結果:

Trace level (after disable): 0

CHECK_SQL_TRACE_EVENT は有効中は内部レベル値（例: 28）を返し、無効化後は 0 に戻ります。これを使えばトレースが確実に停止したことをプログラムで確認できます。

5. トレース結果の確認方法

トレース結果の確認方法は 2 つあります。

5.1. SESSION_CLOUD_TRACE ビュー（SQL による簡易確認）

SESSION_CLOUD_TRACE ビューをクエリすることで DB 上でトレース内容を直接参照できます。
詳細な使い方は前回記事「ADB-S 26ai で 10046/10053 イベントトレースは取れるのか」を参照してください。

-- 行数確認
SELECT COUNT(*) FROM session_cloud_trace;

-- 先頭 10 行確認
SELECT row_number, SUBSTR(trace, 1, 100) AS trace_head
  FROM session_cloud_trace
 ORDER BY row_number
 FETCH FIRST 10 ROWS ONLY;

  COUNT(*)
----------
      2693


ROW_NUMBER TRACE_HEAD                                                                                          
---------- ----------------------------------------------------------------------------------------------------
         1 Oracle AI Database 26ai Enterprise Edition Release 23.26.2.1.0 - Production                         
           Version 23.26.2.1.0                                                                                 
         2 Build label:    RDBMS_23.0.0.0.0_LINUX.X64_260311.ADBS                                              
         3 ORACLE_HOME:    /u02/app/oracle/product/23.0.0.0_260311.ADBS_260418-130346/dbhome_1 
         4 System name:	Linux                                                                  
         5 Node name:	xxxxxxxx                                                               
         6 Release:	5.15.0-308.179.6.7.el8uek.x86_64                                           
         7 Version:	#2 SMP Thu Jun 12 20:04:53 PDT 2025                                        
         8 Machine:	x86_64                                                                     
         9 VM name:	KVM CPUID feature flags: 0x01007abb                                        
        10 Storage:	ASM on Exadata   
        
10行が選択されました。

今回の検証（SQL 2 本）では 2,693 行が書き出されました。先頭約 10 行はシステムヘッダー（OS・Oracle バイナリ・インスタンス情報）です。ADB 環境では Storage: ASM on Exadata と表示され、ADB の基盤が Exadata であることも確認できます。

5.2. Object Storage への出力（標準 .trc ファイル）

DEFAULT_LOGGING_BUCKET が設定されている場合、トレース無効化のタイミングで OCI Object Storage に .trc ファイルが自動出力されます。

ファイル名の規則

sqltrace_{MODULE}_{TRACEFILE_IDENTIFIER}_{SID}_{SERIAL}_{N}.trc

今回の検証では SET_TRACEFILE_IDENTIFIER('userdiag_test') を設定したため、以下のファイルが出力されました。

sqltrace_SQL-Developer_userdiag_test_45688_12042_1.trc
sqltrace_SQL-Developer_userdiag_test_45688_12042_2.trc

TRACEFILE_IDENTIFIER を設定しておくと Object Storage 上での特定が容易になります。

取得したファイルは通常の Oracle トレースファイル

Object Storage からダウンロードした .trc ファイルの冒頭は以下のとおりです。

Oracle AI Database 26ai Enterprise Edition Release 23.26.2.1.0 - Production
...
Storage:	ASM on Exadata
...
*** SESSION ID:(45688.12042) 2026-05-16T23:05:14.680380+00:00
*** MODULE NAME:(SQL Developer)
...
=====================
PARSING IN CURSOR #139881262540360 ...
DECLARE SqlDevBind1Z_1 VARCHAR2(32767):=:SqlDevBind1ZInit1;  BEGIN BEGIN
  DBMS_USERDIAG.ENABLE_SQL_TRACE_EVENT(waits => TO_NUMBER(SqlDevBind1Z_1));
...
EXEC #...:c=1363,e=2068,p=0,cr=4338,...
WAIT #...: nam='SQL*Net message to client' ela=15 ...

オンプレミスの 10046 トレースと完全に同一のフォーマットです。tkprof をはじめ既存のトレース解析ツールがそのまま使えます。

TRACE マーカーの挙動について

DBMS_USERDIAG.TRACE('=== SQL-A START ===') を呼ぶと、binds => 1 設定下では TRACE プロシージャの引数文字列もバインド変数として捕捉されます（value="=== SQL-A START ===" としてトレースに記録）。
マーカー文字列そのものは === SQL-A START === として独立した行で書き出されます。
また binds => 1 は ADB 内部 SQL のバインド変数も捕捉するため、value="DBSNMP" のような内部値が出力に含まれることがあります。

6. DBMS_MONITOR 2ステップ法との比較

前回記事で確認した DBMS_MONITOR 2 ステップ法との違いを整理します。

観点	DBMS_USERDIAG	DBMS_MONITOR 2ステップ
導入バージョン	26ai（新機能）	既存
ADB 26ai で実行可能	✅	✅
waits 取得	✅（`waits=>1`）	✅（`waits=>TRUE`）
binds 取得	✅（`binds=>1`）	✅（`binds=>TRUE`）
STAT 行あり	✅（`plan_stat` で制御可）	✅
plan_stat 制御	✅（4種類）	✅
トレース有効確認	✅（`CHECK_SQL_TRACE_EVENT`）	❌（確認手段なし）
トレースへのマーカー埋め込み	✅（`TRACE` プロシージャ）	❌
呼び出し	1ブロック ON/OFF	2コマンド必要

7. まとめ

#	検証項目	結論
1	`DBMS_USERDIAG` が ADB 26ai で動作し、SESSION_CLOUD_TRACE にトレースが書き出されるか	✅ 2,693 行のトレースが書き出された。WAIT / STAT / BINDS 各行あり
2	`CHECK_SQL_TRACE_EVENT` でトレースの有効/無効を確認できるか	✅ 動作する
3	Object Storage に標準フォーマット（.trc）で出力され、既存ツールで解析できるか	✅ オンプレミスと同一フォーマット。tkprof 等の既存ツールがそのまま利用可能

DBMS_USERDIAG は ADB 26ai 向けに設計された公式の診断パッケージです。
ALTER SESSION SET EVENTS がブロックされるクラウド環境で、従来の DBMS_MONITOR 2 ステップ法よりも豊富な機能（CHECK による状態確認・TRACE マーカー）を提供します。

参考

Oracle Docs: DBMS_USERDIAG (26ai) ↩