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

79 DBMS_HPROF

DBMS_HPROFパッケージは、PL/SQLアプリケーションの実行をプロファイルするためのインタフェースを提供します。階層的なプロファイラ・データの収集、未処理のプロファイラ出力の分析および情報生成のプロファイリングのためのサービスが提供されます。

この章では、次の項目について説明します。

参照:

PL/SQL階層プロファイラの詳細は、『Oracle Database開発ガイド』を参照してください。

79.1 DBMS_HPROFサブプログラムの要約

この表では、DBMS_HPROFパッケージのサブプログラムをリストし、簡単に説明します。

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

サブプログラム 説明

ANALYZEファンクション

未処理のプロファイラ出力を分析し、データベース表の階層プロファイラ情報を生成します。

CREATE_TABLESプロシージャ

ユーザーのセッションで階層プロファイラ・データベース表およびデータ構造を作成します。

START_PROFILINGプロシージャ

ユーザーのセッションで階層プロファイラ・データ収集を開始します。

STOP_PROFILINGプロシージャ

ユーザーのセッションでプロファイラ・データ収集を停止します。

79.1.1 ANALYZEファンクション

このファンクションは、未処理のプロファイラ出力を分析し、データベース表の階層プロファイラ情報を作成するか、デフォルトのHTMLレポートを生成します。

構文

DBMS_HPROF.ANALYZE (
   trace_id         IN NUMBER,
   summary_mode     IN BOOLEAN DEFAULT FALSE,
   trace            IN VARCHAR2 DEFAULT NULL,
   skip             IN PLS_INTEGER DEFAULT 0,
   collect          IN PLS_INTEGER DEFAULT NULL,
   run_comment      IN VARCHAR2 DEFAULT NULL)
  RETURN NUMBER;

DBMS_HPROF.ANALYZE (
   trace_id         IN NUMBER,
   report_clob      OUT CLOB,
   trace            IN VARCHAR2 DEFAULT NULL,
   skip             IN PLS_INTEGER DEFAULT 0,
   collect          IN PLS_INTEGER DEFAULT NULL);

パラメータ

表79-2 ANALYZEファンクションのパラメータ

パラメータ 説明

trace_id

未処理のプロファイラ・データ表(dbmshp_trace_data)の未処理のプロファイラ・データ・エントリのtrace_id。

summary_mode

デフォルトでは(つまり、summary_modeがFALSEの場合)、詳細な分析が実行されます。

summary_modeがTRUEの場合は、トップレベルのサマリー情報のみがデータベース表に生成されます。

report_clob

分析されたHTMLレポート。

trace

指定したトレース・エントリをルートとするサブツリーのみが分析されます。デフォルト(traceがNULLの場合)では、すべての実行に対して分析およびレポート生成が行われます。

トレース・エントリは、引用符で囲まれた特別な修飾形式で指定する必要があります。たとえば、'"HR"."PKG"."FOO"'や'"".""."__plsql_vm"'などです。

指定した名前で複数のオーバーロードがある場合は、該当するすべてが分析されます。

skip

traceを指定した場合にのみ使用します。指定したトレースをルートとするサブツリーのみが分析されますが、最初のskip回分、traceへのコールが無視されます。

skipのデフォルト値は0 (ゼロ)です。

collect

traceを指定した場合にのみ使用します。

collect回数のtraceのコールを分析します(skip+1番目のコールから開始)。

デフォルトでは、1回のコールのみが収集されます。

run_comment

この実行に関してユーザーが指定したコメント。

戻り値

今回のアナライザ実行に対する一意の実行識別子。この識別子を使用すると、この実行に対応する結果を階層プロファイラ表から検索できます。

使用上のノート

  • DBMS_HPROF.CREATE_TABLESサブプログラムを使用して、未処理のプロファイラ・データの分析結果を永続的に格納するための階層プロファイラ・データベース表や他のデータ構造を作成します。

  • デフォルト値(FALSE)が指定されたDBMS_HPROF.CREATE_TABLESをコールしたときに、表がすでに存在する場合は、エラーが発生します。

  • DBMS_HPROF.CREATE_TABLES(TRUE)を使用して、以前に作成されたすべての階層プロファイラ表を削除します。

  • DBMS_HPROF.CREATE_TABLESを使用して、以前に作成されたすべての階層プロファイラ表を削除します。デフォルトでは、force_itがFALSEであるため、以前に作成されたすべての階層プロファイラ表を削除するには、force_itの値をTRUEに設定する必要があります。

  • trace_idエントリがNULLの場合は、エラーが発生します。

  • 未処理のプロファイラ・データ表のtrace_idエントリが存在しない場合は、エラーが発生します。

  • 未処理のプロファイラ・データ表のtrace_idエントリのRAWデータがNULLまたはzeroサイズの場合は、エラーが発生します。

例

次のコマンドでは、階層プロファイラ表がHRスキーマにインストールされます。

connect HR/<password>;

次の例では、未処理のプロファイラ・データ表を分析して、HTML CLOBレポートを生成します。

DECLARE
        reportclob clob;
        trace_id number;
BEGIN
    -- create raw profiler data and analysis tables
    -- force_it =>TRUE will dropped the tables if table exists
    DBMS_HPROF.CREATE_TABLES(force_it =>TRUE);

    -- Start profiling
    -- Write raw profiler data in raw profiler data table
    trace_id := DBMS_HPROF.START_PROFILING;

    -- Run procedure to be profiled
    test;

    -- Stop profiling
    DBMS_HPROF.STOP_PROFILING;

    -- analyzes trace_id entry in raw profiler data table and produce
    -- analyzed HTML report in reportclob
    DBMS_HPROF.ANALYZE(trace_id , reportclob);
END;
/

79.1.2 CREATE_TABLESプロシージャ

ユーザーのセッションで階層プロファイラ・データベース表およびデータ構造を作成します。

構文

DBMS_HPROF.CREATE_TABLES (
   force_it         IN BOOLEAN DEFAULT FALSE);

パラメータ

表79-3 CREATE_TABLESプロシージャのパラメータ

パラメータ 説明

force_it

FALSEが指定され、DBMS_HPROF表が存在する場合は、HPROFエラーが発生します。

TRUEの場合は、プロシージャにより表が作成されます。表がすでに存在する場合は削除され、新しい表が作成されます。

ノート:

ユーザーは、rdbms/adminディレクトリにあるdbmshptab.sqlスクリプトを使用して、階層プロファイラ・データベース表やデータ構造を作成する必要はありません。

dbmshptab.sqlスクリプトは、Oracle Database 18c以降では推奨されていません。

79.1.3 START_PROFILINGプロシージャ

このプロシージャは、ユーザーのセッションで階層プロファイラ・データ収集を開始します。

構文

DBMS_HPROF.START_PROFILING(
   max_depth     IN PLS_INTEGER DEFAULT NULL,
   sqlmonitor    IN BOOLEAN DEFAULT TRUE,
   run_comment   IN VARCHAR2 DEFAULT NULL)
RETURN NUMBER;

パラメータ

表79-4 START_PROFILINGプロシージャのパラメータ

パラメータ 説明

max_depth

デフォルト(つまり、max_depth値がNULLの場合)では、コールの深さに関係なく、すべてのファンクションのプロファイル情報が収集されます。max_depthにNULL以外の値を指定した場合は、コールの深さが最大でmax_depthのレベルまでのファンクションのデータのみが、プロファイラによって収集されます。

sqlmonitor

プロファイラ実行が終了したときに、プロファイラ実行のリアルタイム監視レポートを生成します。

デフォルト値はTRUEです。

run_comment

プロファイラ・データ収集実行のためにユーザーが入力したコメント。

戻り値

このプロファイラ実行の一意の実行識別子。この識別子を使用すると、この実行に対応する結果を階層プロファイラ表から検索できます。

使用上のノート

  • プロファイラは、max_depthの値よりも深いファンクションを個別に追跡しませんが、これらのファンクションで消費された時間は、max_depthの深さの祖先ファンクションに含まれます。

  • 未処理のプロファイラ・データは、一意のtrace_idとともに未処理のプロファイラ・データ表に生成されます。

  • 一意のtrace_idを使用して、未処理のプロファイラ・データ表に格納されている未処理のプロファイラ出力を管理します。

79.1.4 STOP_PROFILINGプロシージャ

このプロシージャは、ユーザーのセッションでプロファイラ・データ収集を停止します。また、このサブプログラムには、それまでにセッションで収集したデータをフラッシュする副次効果があり、これが実行の終了を示します。STOP_PROFILINGプロシージャがCLOBを戻した場合は、プロファイラ実行のリアルタイム監視レポートが含まれています。

構文

DBMS_HPROF.STOP_PROFILING;


DBMS_HPROF.STOP_PROFILING
  RETURN CLOB;

例

未処理のプロファイラ・データ表でのプロファイル

DECLARE
    analyze_runid number;
    trace_id number;
BEGIN
    -- create raw profiler data and analysis tables
    -- call create_tables with force_it =>FALSE (default) when
    -- raw profiler data and analysis tables do not exist already
    DBMS_HPROF.CREATE_TABLES;
    -- Start profiling
    -- Write raw profiler data in raw profiler data table
    trace_id := DBMS_HPROF.START_PROFILING;
    -- Run the procedure to be profiled
    test;
    -- Stop profiling
    DBMS_HPROF.STOP_PROFILING;
    -- analyzes trace_id entry in raw profiler data table and writes
    -- hierarchical profiler information in hprof’s analysis tables
    analyze_runid := DBMS_HPROF.ANALYZE(trace_id);
END;
/