1. PL/SQLパッケージおよびタイプ・リファレンス
  2. DBMS_USERDIAG

202 DBMS_USERDIAG

DBMS_USERDIAGパッケージを使用すると、PDBに対して限定された一連の診断操作を実行できます。

この章のトピックは、次のとおりです:

クラウドでトレースを有効にするには、Autonomous DatabaseでのSQLトレースの実行に記載されている追加の構成が必要です。

202.1 DBMS_USERDIAGの概要

DBMS_USERDIAGパッケージは診断用であり、PDB内でトレースを設定できます。

DBMS_USERDIAGパッケージは、DBMS_SYSTEM機能の下で利用されますが、任意のイベント設定を制限する限定された一連の定義を使用します。

指定したPDBについて、DBMS_USERDIAGパッケージでは次のことができます。

  • 指定したレベルでSQLトレースを有効にします。
  • SQLトレースを無効にします。
  • SQLトレースをチェックします。

通常の診断メカニズムのほとんどは、ロックダウン・プロファイルを使用して、指定したPDBの外部で制限されているため、クラウド・インスタンスのCBDデプロイメントで共有テナンシのユーザー・セッションから任意のイベントを有効にすることはできません。特に、"alter session set events"文は、コードパスの実行を変更したり、エラーをシミュレートする可能性のあるイベント/アクションを設定するために悪用されることがあるため、クラウド・デプロイメントではブロックされています。

202.2 DBMS_USERDIAGサブプログラムの要約

DBMS_USERDIAGパッケージでは、ENABLE_SQL_TRACE_EVENTおよびCHECK_SQL_TRACE_EVENTサブプログラムを使用して、sql_traceイベントを有効化、無効化および監視します。

表202-1 DBMS_USERDIAGパッケージのサブプログラム

サブプログラム 説明
CHECK_SQL_TRACE_EVENTプロシージャ

現在のsql_traceイベントをチェックし、そのレベルを取得します。

ENABLE_SQL_TRACE_EVENTプロシージャ

ユーザー・セッションにおいて指定されたlevelでsql_traceイベントを有効にし、それぞれのプロセス・トレース・ファイルにSQLトレースを生成します。

GET_CALL_ERROR_MSGファンクション

DBMS_USERDIAG APIへの最後のコールでエラーが戻された場合にエラー・メッセージを取得します。

GET_CALL_STATUSファンクション

DBMS_USERDIAG APIへの最後のコールのステータスを取得します。

SET_EXCEPTION_MODEプロシージャ

エラーに対して例外を生成するか、同じものをサイレントで無視します(デフォルト)。
SET_TRACEFILE_IDENTIFIERプロシージャ

現在のADRホームのアクティブなトレース・ファイルについてカスタム・トレース・ファイル識別子を設定します。
TRACEプロシージャ

トレース・ファイルまたはアラート・ログへのメッセージをトレースします。

202.2.1 CHECK_SQL_TRACE_EVENTプロシージャ

このプロシージャは、現在のユーザーが現在のsql_traceイベントをチェックし、そのレベルを取得するために使用できます。

構文

DBMS_USERDIAG.CHECK_SQL_TRACE_EVENT(
   sql_id                IN VARCHAR2       DEFAULT NULL
   sys                   IN BINARY_INTEGER DEFAULT NULL
   level                 OUT BINARY_INTEGER);

パラメータ

表202-2 CHECK_SQL_TRACE_EVENTプロシージャのパラメータ

パラメータ 説明

level

必須。sql_traceイベントが有効になっている現在のレベルの出力。

sql_id

指定されたsql_idのみの範囲内のsql_trace。これは現在無視されます。

sys

オプション。イベントをインスタンス全体またはPDB全体に設定します。デフォルトは0です。これは現在無視されます。

202.2.2 ENABLE_SQL_TRACE_EVENTプロシージャ

このプロシージャは、ユーザー・セッションにおいて指定されたlevelでsql_traceイベント(sql_trace/10046)を有効にし、それぞれのプロセス・トレース・ファイルにSQLトレースを生成します。

オプションでsql_idも指定でき、この場合は、そのsql_idのみについてトレースが有効になります。デフォルトでは、SQLの範囲なしでイベントが有効になります。デフォルトでは、現在のセッションのみでイベントが設定されます。イベントを無効にするには、disableをゼロ以外の値に設定します(デフォルトはゼロです)。

構文

DBMS_USERDIAG.ENABLE_SQL_TRACE_EVENT(
   level                 IN  BINARY_INTEGER DEFAULT 1,
   sid                   IN  BINARY_INTEGER DEFAULT 0,
   ser                   IN  BINARY_INTEGER DEFAULT 0,
   binds                 IN  BINARY_INTEGER DEFAULT 0,
   waits                 IN  BINARY_INTEGER DEFAULT 0,
   plan_stat             IN  VARCHAR2       DEFAULT NULL,
   sql_id                IN  VARCHAR2       DEFAULT NULL,
   disable               IN  BINARY_INTEGER DEFAULT 0,
   sys                   IN  BINARY_INTEGER DEFAULT 0);

パラメータ

表202-3 ENABLE_SQL_TRACE_EVENTプロシージャのパラメータ

パラメータ 説明

level

オプション。sql_traceイベントに関連付けられたレベルを指定します。他の設定によって、このレベル値が大きくなります。たとえば、binds=>trueを指定すると、ユーザーが指定したレベル値よりも大きくなります。これは、使いやすさのために保持されます。

sid

オプション。ターゲット・セッション識別子。

sid、serペアは、現在のPDB ID内にあることが検証される必要があります。

ser

オプション。ターゲットのシリアル番号。

binds

オプション。ゼロ以外の値を指定すると、バインド値がトレースされます。レベル4にマップします。

waits

オプション。ゼロ以外の値を指定すると、待機がトレースされます。レベル8にマップします。

plan_stat

オプション。指定可能な値: FIRST_EXECUTION (デフォルト)、NEVER、ALL_EXECUTIONSおよびADAPTIVE

sql_id

指定されたsql_idのみの範囲内でsql_traceを有効にします

disable

オプション。ゼロ以外の値を指定すると、すでに設定されているsql_traceイベントが無効になります。

sys

オプション。イベントをインスタンス全体またはPDB全体に設定します。デフォルトは0です。

202.2.3 GET_CALL_ERROR_MSGファンクション

このファンクションは、DBMS_USERDIAG APIへの最後のコールでエラーが戻された場合にエラー・メッセージを取得するために使用します。

構文

DBMS_USERDIAG.GET_CALL_ERROR_MSG RETURN VARCHAR2;

戻り値

DBMS_USERDIAGへの前のコールが失敗した場合、VARCHAR2には、関連付けられているエラー・メッセージが含まれます。

DBMS_USERDIAGへの前のコールが成功した場合、戻される値はNULLです。

202.2.4 GET_CALL_STATUSファンクション

このファンクションは、DBMS_USERDIAG APIへの最後のコールのステータスを取得するために使用します。

構文

DBMS_USERDIAG.GET_CALL_STATUS RETURN NUMBER;

戻り値

DBMS_USERDIAG APIへの最後のコールのステータスを示す数値を戻します。

前のコールが成功した場合、このコールの値はNOERROR(0)です。

前のコールが失敗した場合、このコールの値はエラー・コード番号です。

202.2.5 SET_EXCEPTION_MODEプロシージャ

このプロシージャは、エラーに対して例外を生成するか、同じものをサイレントで無視します(デフォルト)。

構文

DBMS_USERDIAG.SET_EXCEPTION_MODE(
   exc_mode IN BOOLEAN DEFAULT FALSE);

パラメータ

表202-4 SET_EXCEPTION_MODEプロシージャのパラメータ

パラメータ 説明

exc_mode

TRUEの場合、エラーに対して例外が生成されます。

FALSE (デフォルト)の場合、エラーは無視されます。

202.2.6 SET_TRACEFILE_IDENTIFIERプロシージャ

このプロシージャは、現在のADRホームのアクティブなトレース・ファイルについてカスタム・トレース・ファイル識別子を設定するために使用します。

構文

DBMS_USERDIAG.SET_TRACEFILE_IDENTIFIER(
   trc_identifier IN VARCHAR2);

パラメータ

表202-5 SET_TRACEFILE_IDENTIFIERプロシージャのパラメータ

パラメータ 説明

trc_identifier

現在のADRホームのアクティブなトレース・ファイルのトレース識別子を指定します。

202.2.7 TRACEプロシージャ

このプロシージャは、トレース・ファイルまたはアラート・ログへのメッセージをトレースするために使用します。

構文

DBMS_USERDIAG.TRACE(
   message IN VARCHAR2, 
   alert   IN BOOLEAN   DEFAULT FALSE);

パラメータ

表202-6 TRACEプロシージャのパラメータ

パラメータ 説明

message

トレースするテキストまたはメッセージを指定します。

alert

TRUEの場合、アラート・ログがトレース・ファイルとともにトレース操作の対象として含まれます。

FALSE (デフォルト)の場合、アラート・ログは無視され、トレース・ファイルのみがトレース操作に使用されます。