2026年5月17日の情報です
1. はじめに
前回記事「ADB-S 26ai で 10046/10053 イベントトレースは取れるのか」では、DBMS_MONITOR を使った 2 ステップ回避策で待機イベントつきトレースが取れることを確認しました。
今回はその続編として、Oracle Autonomous Database Serverless（以下 ADB-S）上の Oracle AI Database 26ai で正式追加された DBMS_USERDIAG パッケージ1 を実機で検証します。このパッケージは「クラウド 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_MONITOR2 ステップ法との違いは §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: アプリケーション・トレースの実行 (26ai)
- Oracle Docs: Autonomous AI Database でのアプリケーション・トレースの実行
- 前回記事: ADB-S 26ai で 10046/10053 イベントトレースは取れるのか