171 DBMS_TRACE

DBMS_TRACEパッケージには、PL/SQLファンクション、プロシージャ、例外をトレースするインタフェースが含まれます。

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

171.1 DBMS_TRACEの概要

DBMS_TRACEは、セッションでPL/SQLトレースを開始および停止するサブプログラムを提供します。トレース・データはプログラムの実行時に収集され、データベース表に書き込まれます。

一般的なセッションには、次の処理が含まれます。

  1. (オプション)トレースを特定のサブプログラムに制限し、トレース・レベルを選択します。

    大規模なプログラムのすべてのサブプログラムおよび例外をトレースすると、大量のデータが生成されて管理が困難になることがあります。
  2. セッションでPL/SQLトレースを開始します(DBMS_TRACE.SET_PLSQL_TRACE)。

  3. トレースするアプリケーションを実行します。

  4. セッションでPL/SQLトレースを停止します(DBMS_TRACE.CLEAR_PLSQL_TRACE)。

トレースでデータを収集した後で、パフォーマンス・データが含まれているデータベース表を問い合せて、プロファイラからパフォーマンス・データを分析する方法と同じ方法で分析できます。

171.2 DBMS_TRACEのセキュリティ・モデル

このパッケージは、SYSの下に作成する必要があります。

171.3 DBMS_TRACEの定数

DBMS_TRACEは、パラメータ値の指定時に使用する定数を定義します。

これらの定数を、次の表に示します。

表171-1 DBMS_TRACEのイベント定数

名前 タイプ 説明

TRACE_ALL_CALLS

INTEGER

1

コールまたは戻り値をトレースします。

TRACE_ENABLED_CALLS

INTEGER

2

TRACE_ALL_EXCEPTIONS

INTEGER

4

例外をトレースします。

TRACE_ENABLED_EXCEPTIONS

INTEGER

8

例外およびハンドラをトレースします。

TRACE_LIMIT

INTEGER

16

最新の数レコードのみを保存します。これにより、大量の無関係な情報でデータベースをいっぱいにすることなく、問題領域までトレースできます。イベント10940を設定した場合の制限は、1023*(イベント10940の値)です。この制限は、"TRACE_LIMIT"フラグを使用して上書きできます。

TRACE_ALL_SQL

INTEGER

32

SQL文をトレースします。

TRACE_ENABLED_SQL

INTEGER

64

SQL文をPL/SQLレベルでトレースします。これによりSQLトレースが起動されることはありません。

TRACE_ALL_LINES

INTEGER

128

各行をトレースします。

TRACE_ENABLED_LINES

INTEGER

256

TRACE_PAUSE

INTEGER

4096

トレースを一時停止します。

TRACE_RESUME

INTEGER

8192

トレースを再開します。

TRACE_STOP

INTEGER

16384

トレースを停止します。

NO_TRACE_ADMINISTRATIVE

INTEGER

32768

次のような管理イベントのトレースを抑制します。

  • PL/SQLトレースツールが起動した

  • トレース・フラグが変更された

  • PL/SQL仮想マシンが起動した

  • PL/SQL仮想マシンが停止した

NO_TRACE_HANDLED_EXCEPTIONS

INTEGER

65536

処理済の例外のトレースを抑制します。

表171-2 DBMS_TRACEのバージョン定数

名前 タイプ 説明

TRACE_MINOR_VERSION

INTEGER

0

TRACE_MAJOR_VERSION

INTEGER

1

これらの定数についてはすべて記号形式(定数名)を使用することをお薦めします。

171.4 DBMS_TRACEの制限事項

PL/SQLトレースは、共有サーバー環境では使用できません。

171.5 DBMS_TRACEの使用上の注意

DBMS_TRACEには、特定の使用上の注意が適用されます。

データ量の制御

大規模なアプリケーションをプロファイルすると、データ量が膨大になる可能性があります。トレース・データの収集に関する特定のプログラム・ユニットを使用可能にして、収集するデータ量を制御できます。

プログラム・ユニットは、コンパイルとデバッグを行って使用可能にできます。次のいずれかの方法で行います。

alter session set plsql_debug=true; 
create or replace ... /* create the library units - debug information will be generated */ 

または

/* recompile specific library unit with debug option */ 
alter [PROCEDURE | FUNCTION | PACKAGE BODY]  <libunit-name> compile debug; 

注意:

2番目の方法は、無名ブロックに対しては使用できません。

SET_PLSQL_TRACEプロシージャのTRACE_LEVELパラメータにTRACE_LIMITを指定することにより、最新の8,192レコード(概算)のみを保持して、データベースで使用する記憶域量を制限できます。

DBMS_TRACE出力を収集するデータベース表の作成

DBMS_TRACEパッケージで出力を書き込むためのデータベース表を作成する必要があります。作成しないと、データが収集されません。このような表を作成するには、TRACETAB.SQLスクリプトを実行してください。このスクリプトで作成した表の所有者は、SYSです。

トレース・データの収集

トレース可能なPL/SQL機能は、DBMSPBT.SQLスクリプトに記述されています。主なトレース機能は次のとおりです。

  • コールのトレース

  • 例外のトレース

  • SQLのトレース

  • 行のトレース

DBMS_TRACEの追加機能として、トレースの解析と再開および出力の制限もできます。

コールのトレース

使用可能なコールのトレースには、次の2つのレベルがあります。

  • レベル1: すべてのコールをトレースします。これは、定数TRACE_ALL_CALLSに対応します。

  • レベル2: 使用可能なプログラム・ユニットのみ、コールをトレースします。これは、定数TRACE_ENABLED_CALLSに対応します。

リモート・プロシージャ・コール(RPC)については、使用可能かどうかを検出できないため、RPCではレベル1でのみトレースできます。

例外のトレース

使用可能な例外のトレースには、次の2つのレベルがあります。

  • レベル1: すべての例外をトレースします。これは、定数TRACE_ALL_EXCEPTIONSに対応します。

  • レベル2: 使用可能なプログラム・ユニットのみ、発生した例外をトレースします。これは、定数TRACE_ENABLED_EXCEPTIONSに対応します。

SQLのトレース

使用可能なSQLのトレースには、次の2つのレベルがあります。

  • レベル1: すべてのSQLをトレースします。これは、定数TRACE_ALL_SQLに対応します。

  • レベル2: 使用可能なプログラム・ユニットでのみ、SQLをトレースします。これは、定数TRACE_ENABLED_SQLに対応します。

行のトレース

使用可能な行のトレースには、次の2つのレベルがあります。

  • レベル1: すべての行をトレースします。これは、定数TRACE_ALL_LINESに対応します。

  • レベル2: 使用可能なプログラム・ユニットでのみ、行をトレースします。これは、定数TRACE_ENABLED_LINESに対応します。

行のトレース時には、行番号が変わるたびにレコードがデータベースに追加されます。プロシージャのコールおよびその戻り値によって行番号が変わる場合も、トレースの対象に含まれます。

注意:

すべてのタイプのトレースでは、レベル1がレベル2を上書きします。たとえば、レベル1とレベル2の両方が使用可能な場合は、レベル1が優先されます。

収集されるデータ

使用可能なプログラム・ユニットについてのみトレースが要求されていて、現行のプログラム・ユニットが使用可能ではない場合、トレース・データは書き込まれません。

コールをトレースする場合は、コールと戻り値の両方がトレースされます。トレースが使用可能であるかどうかのチェックは、コールされるルーチンまたはコールするルーチンのいずれか一方が使用可能な場合に、トレース実施と判断されます。

コールのトレースでは、必ずコール元とコール先の両方のプログラム・ユニットのタイプ、プログラム・ユニット名、および行番号が出力されます。これにより、コール元のスタックの深さが出力されます。コール元が使用可能な場合は、コール元の名前も出力されます。コールされる側が使用可能な場合は、コールされる側の名前も出力されます。

例外トレースでは、行番号が書き込まれます。例外が発生すると、その例外がユーザー定義か事前定義のいずれかであるかが示されます。事前定義の例外の場合は例外番号も出力されます。例外が発生した場所とそのハンドラの両方がトレースされます。トレースが使用可能であるかどうかのチェックは、例外が発生した場所と例外がハンドルされた場所で個別に行われます。NO_TRACE_HANDLED_EXCEPTIONSを有効にすると、データ収集の対象が未処理の例外のみに制限されます。

DBMS_TRACE.SET_PLSQL_TRACEおよびDBMS_TRACE.CLEAR_PLSQL_TRACEへのコールによって、データベースに特別なトレース・レコードが配置されます。したがって、トレース設定が変更された時点を常に確認できます。

トレース管理

収集した項目を確認するのみではなく、トレース処理を一時停止したり、再開することもできます。トレースが一時停止されてから再開されるまでの間、情報は収集されません。一時停止および再開には、それぞれ定数TRACE_PAUSEおよびTRACE_RESUMEを使用します。トレースが一時停止または再開したことを示すためにトレース・レコードが生成されます。

定数TRACE_LIMITを使用すると、最新の8,192トレース・イベントのみを保持できます。これにより、データベースをいっぱいにすることなくトレースを繰り返すことができます。トレースの停止時には、最新の8,192レコードが保存されています。この制限はトレース・レコードごとにチェックされないため概算です。少なくとも要求されたトレース・レコードの数は生成され、1,000レコードまでは追加生成できます。少なくとも要求されたトレース・レコードの数は生成され、1,000レコードまでは追加生成できます。8,192というレコード数の制限は変更できます。イベント10940をレベルnに設定すると、レコード制限は1024 * nに変更されます。

NO_TRACE_ADMINISTRATIVEを有効にすると、PL/SQLトレース・ツールが起動したトレース・フラグが変更されたPL/SQL仮想マシンが起動したPL/SQL仮想マシンが停止したなどの管理イベント・レコードが生成されなくなります。

171.6 DBMS_TRACEサブプログラムの要約

この表は、DBMS_TRACEサブプログラムを示し、簡単に説明しています。

表171-3 DBMS_TRACEパッケージのサブプログラム

サブプログラム 説明

CLEAR_PLSQL_TRACEプロシージャ

セッションでのトレース・データのダンプを停止します。

GET_PLSQL_TRACE_LEVELファンクション

トレース・レベルを取得します。

PLSQL_TRACE_VERSIONプロシージャ

トレース・パッケージのバージョン番号を取得します。

SET_PLSQL_TRACEプロシージャ

現行のセッションでトレースを開始します。

171.6.1 CLEAR_PLSQL_TRACEプロシージャ

このプロシージャは、トレース・データ収集を使用禁止にします。

構文

DBMS_TRACE.CLEAR_PLSQL_TRACE; 

171.6.2 GET_PLSQL_TRACE_LEVELファンクション

このプロシージャは、1つ以上のDBMS_TRACE定数の和として現行トレース・レベルを戻します。

定数のリストについては、表171-1を参照してください。

構文

DBMS_TRACE.GET_PLSQL_TRACE_LEVEL 
  RETURN BINARY_INTEGER; 

171.6.3 PLSQL_TRACE_VERSIONプロシージャ

このプロシージャは、トレース・パッケージのバージョン番号を取得します。DBMS_TRACEパッケージのバージョン番号とリリース番号を戻します。

構文

DBMS_TRACE.PLSQL_TRACE_VERSION ( 
   major OUT BINARY_INTEGER, 
   minor OUT BINARY_INTEGER); 

パラメータ

表171-4 PLSQL_TRACE_VERSIONプロシージャのパラメータ

パラメータ 説明

major

DBMS_TRACEのバージョン番号。

minor

DBMS_TRACEのリリース番号。

171.6.4 SET_PLSQL_TRACEプロシージャ

このプロシージャは、PL/SQLのトレース・データ収集を可能にします。

構文

DBMS_TRACE.SET_PLSQL_TRACE ( 
   trace_level INTEGER); 

パラメータ

表171-5 SET_PLSQL_TRACEプロシージャのパラメータ

パラメータ 説明

trace_level

表171-1にリストされている1つ以上の定数を指定する必要があります。定数を合計することにより、複数のPL/SQL言語機能のトレースを同時に使用可能にできます。制御定数TRACE_PAUSETRACE_RESUMEおよびTRACE_STOPは、他の定数と組み合せて使用しないでください。

詳細は、「DBMS_TRACEの使用上の注意: トレース・データの収集」を参照してください。