polar_plsql_profiler で PL/SQL パフォーマンスをプロファイリング - PolarDB

複雑な PL/SQL 関数やストアドプロシージャのパフォーマンスボトルネックを特定することは、困難な場合があります。polar_plsql_profiler 拡張機能は、PL/SQL コードの実行を監視および記録することで、パフォーマンスの最適化を支援します。これにより、各コード行の実行時間や関数間の呼び出し関係を分析できます。

概要

polar_plsql_profiler はパフォーマンス分析ツールです。PL/SQL 実行エンジンにアタッチして、ランタイムでパフォーマンスデータを収集します。このデータには、各コード行の実行回数と合計実行時間が含まれます。また、呼び出し階層や関数間の時間配分も含まれます。アナライザは収集したデータを現在のセッションのメモリに保存します。その関数を呼び出すことで、分析結果を構造化データまたは視覚的な HTML レポートとして表示できます。

適用範囲

この拡張機能は、PolarDB for PostgreSQL (Oracle 互換) の Oracle 構文互換性 2.0 でサポートされています。マイナーエンジンバージョンは 2.0.14.19.40.0 以降である必要があります。

説明

マイナーエンジンバージョンは、コンソールで表示するか、SHOW polardb_version; 文を実行して確認できます。ご利用のマイナーエンジンバージョンが要件を満たしていない場合は、マイナーエンジンバージョンをアップグレードしてください。

利点

行レベルのコード分析：ソースコードの各行の実行回数と実行時間を特定し、ホットスポットを迅速に特定します。
コールグラフ：関数間の呼び出し関係を明確に示します。これにより、合計実行時間がさまざまな関数モジュールにどのように分散されているかを理解するのに役立ちます。
視覚的なレポート：単一のコマンドで詳細な HTML レポートを生成し、分析と共有を容易にします。

注意事項

パフォーマンスオーバーヘッド：パフォーマンス分析を有効にすると、追加のオーバーヘッドが発生します。この機能は、開発またはパフォーマンス診断にのみ使用してください。本番環境で長時間有効にしたままにすることは避けてください。
セッションレベル：アナライザによって収集されたデータは、現在のデータベースセッションでのみ有効です。セッションが切断されると、すべての分析データは失われます。
迅速なクリーンアップ：分析が完了したら、速やかにアナライザを無効にしてデータをクリアしてください。これにより、リソースが解放され、パフォーマンスへの影響がなくなります。

ユーザーガイド

このガイドでは、ツールの使用方法を説明するために 2 つの例を示します。1 つ目はクイックスタートの例です。2 つ目は、サブ関数の呼び出しを含む複雑なシナリオを分析する方法を示します。

クイックスタートと基本分析

この例では、基本的なパフォーマンス分析のワークフローを順を追って説明します。

ステップ 1：拡張機能のインストール

開始する前に、拡張機能を作成し、アナライザを有効にします。その後、アナライザは現在のセッションですべての PL/SQL コードの実行の監視を開始します。

-- 拡張機能が存在しない場合は作成します。
CREATE EXTENSION polar_plsql_profiler;

ステップ 2：サンプルコードの準備

分析したい PL/SQL 関数またはストアドプロシージャを実行します。次のコードはサンプル関数を提供します。

-- テスト用の関数を作成します。
CREATE OR REPLACE FUNCTION simple_test_func(p_times IN NUMBER)
RETURNS VARCHAR2 AS
    v_result VARCHAR2(100);
BEGIN
    FOR i IN 1 .. p_times LOOP
        v_result := 'Iteration ' || i;
    END LOOP;
    RETURN v_result;
END;

ステップ 3：アナライザの有効化

アナライザを起動します。成功した場合、コマンドは t を返します。

SELECT plsql_profiler_enable();

ステップ 4：ターゲットコードの実行

関数を実行してデータを収集します。

SELECT simple_test_func(100);

ステップ 5：パフォーマンスデータの分析

収集されたパフォーマンスデータは、いくつかの方法で表示できます。

関数呼び出しの概要の表示

plsql_profiler_show_funclist() 関数を使用すると、分析中に呼び出されたすべての関数の全体的なパフォーマンス統計を表示できます。これにより、実行時間が最も長い関数をすばやく特定できます。

SELECT * FROM plsql_profiler_show_funclist();

次の結果が返されます。

              func_call               | func_oid_list | call_count | us_total | us_declare | us_children | us_self |          time_stamp           
--------------------------------------+---------------+------------+----------+------------+-------------+---------+-------------------------------
 oid=21749  public.simple_test_func() | {21749}       |          1 |      303 |         13 |           0 |     303 | 2026-01-05 06:01:20.619468+00

特定の関数の行レベルの詳細の表示

ターゲット関数を特定した後、plsql_profiler_show_function() を使用して、関数内の各コード行の詳細なパフォーマンスデータを表示できます。

-- まず、関数リストからターゲット関数の OID 配列 (func_oid_list) を取得します。
-- 次に、この OID 配列をパラメーターとして次の関数に渡します。
SELECT * FROM plsql_profiler_show_function(ARRAY['...']); -- '...' を関数の OID リストに置き換えてください。

例

SELECT * FROM plsql_profiler_show_function(ARRAY[21749]);

次の出力が返されます。

 line_number | exec_count | total_time | percent | avg_time | min_time | max_time |              source_code               | time_stamp 
-------------+------------+------------+---------+----------+----------+----------+----------------------------------------+------------
           0 |          1 |        303 |     100 |      303 |      303 |      303 |  ---- Function Totals ----             | 
           1 |          0 |          0 |       0 |        0 |        0 |        0 | v_result VARCHAR2(100);                | 
           2 |          1 |        287 |   94.72 |      287 |      287 |      287 | BEGIN                                  | 
           3 |          1 |        276 |   91.09 |      276 |      276 |      276 |     FOR i IN 1 .. p_times LOOP         | 
           4 |        100 |        145 |   47.85 |        1 |        0 |      145 |         v_result := 'Iteration ' || i; | 
           5 |          0 |          0 |       0 |        0 |        0 |        0 |     END LOOP;                          | 
           6 |          1 |          0 |       0 |        0 |        0 |        0 |     RETURN v_result;                   | 
           7 |          0 |          0 |       0 |        0 |        0 |        0 | END;                                   |

ステップ 6：リソースのクリーンアップ

分析が完了したら、データをリセットし、アナライザを無効にし、拡張機能を削除します。これにより、後続の操作へのパフォーマンスへの影響を回避できます。

-- 1. (オプション) 収集した分析データをリセットします。
SELECT plsql_profiler_reset();

-- 2. アナライザを無効にします。
SELECT plsql_profiler_disable();

-- 3. (オプション) 不要になった場合は、拡張機能を削除します。
DROP EXTENSION polar_plsql_profiler;

高度な分析とボトルネックの特定 (サブ関数の呼び出しを含む)

この例では、メイン関数が時間のかかるサブ関数を呼び出す、より現実的なシナリオをシミュレートします。この例では、アナライザを使用して実際のパフォーマンスボトルネックを見つける方法を示します。

ステップ 1：拡張機能のインストール

-- 拡張機能が存在しない場合は作成します。
CREATE EXTENSION polar_plsql_profiler;

ステップ 2：サンプルコードの準備

まず、サブ関数を含む複雑なパッケージを作成します。

-- サブ関数を含む複雑なパッケージを作成します。
CREATE OR REPLACE PACKAGE complex_pkg AS
    FUNCTION calculate_tax(p_salary NUMBER) RETURN NUMBER;
    PROCEDURE process_payroll(p_dept_id NUMBER);
END complex_pkg;

CREATE OR REPLACE PACKAGE BODY complex_pkg AS
    FUNCTION calculate_tax(p_salary NUMBER) RETURN NUMBER IS
        v_tax_amount NUMBER;
        -- サブ関数
        FUNCTION get_tax_rate(p_income NUMBER) RETURN NUMBER IS
            v_rate NUMBER;
        BEGIN
            IF p_income <= 50000 THEN
                v_rate := 0.10;
            ELSIF p_income <= 100000 THEN
                v_rate := 0.20;
            ELSE
                v_rate := 0.30;
            END IF;
            RETURN v_rate;
        END get_tax_rate;
    BEGIN
        v_tax_amount := p_salary * get_tax_rate(p_salary);
        RETURN v_tax_amount;
    END calculate_tax;

    PROCEDURE process_payroll(p_dept_id NUMBER) IS
    BEGIN
        -- いくつかの操作を実行します。
        NULL;
    END process_payroll;
END complex_pkg;

ステップ 3：アナライザの有効化

アナライザを起動します。成功した場合、コマンドは t を返します。

SELECT plsql_profiler_enable();

ステップ 4：ターゲットコードの実行

関数を実行してデータを収集します。

SELECT complex_pkg.calculate_tax(75000);

ステップ 5：パフォーマンスデータの分析

収集されたパフォーマンスデータは、いくつかの方法で表示できます。

関数呼び出しの概要の表示

SELECT * FROM plsql_profiler_show_funclist();

次の結果が返されます。

                  func_call                  |   func_oid_list    | call_count | us_total | us_declare | us_children | us_self |          time_stamp           
---------------------------------------------+--------------------+------------+----------+------------+-------------+---------+-------------------------------
 oid=0  inline_code_block                    | {0}                |          1 |       24 |         19 |           0 |      24 | 2026-01-05 04:03:37.68941+00
 oid=21721  complex_pkg.calculate_tax()      | {21721}            |          1 |     1309 |          8 |         815 |     494 | 2026-01-05 04:03:37.689697+00
 oid=21721  complex_pkg.calculate_tax()     +| {21721,4294957297} |          1 |      815 |          9 |           0 |     815 | 2026-01-05 04:03:37.690177+00
 oid=4294957297    ->  public.get_tax_rate() |                    |            |          |            |             |         | 
(3 rows)

特定の関数の行レベルの詳細の表示

ターゲット関数を特定した後、plsql_profiler_show_function() 関数を使用して、各コード行の詳細なパフォーマンスデータを表示できます。

-- まず、関数リストから目的の関数の OID 配列 (func_oid_list) を取得します。
-- 次に、OID 配列をパラメーターとして次の関数に渡します。
SELECT * FROM plsql_profiler_show_function(ARRAY['...']); -- '...' を関数の OID のリストに置き換えてください。

例

SELECT * FROM plsql_profiler_show_function(ARRAY[21721,4294957297]);

次の出力が返されます。

 line_number | exec_count | total_time | percent | avg_time | min_time | max_time |                source_code                | time_stamp 
-------------+------------+------------+---------+----------+----------+----------+-------------------------------------------+------------
           0 |          1 |        351 |     100 |      351 |      351 |      351 |  ---- Function Totals ----                | 
           1 |          0 |          0 |       0 |        0 |        0 |        0 | v_rate NUMBER;                            | 
           2 |          1 |        340 |   96.87 |      340 |      340 |      340 |         BEGIN                             | 
           3 |          1 |        338 |    96.3 |      338 |      338 |      338 |             IF p_income <= 50000 THEN     | 
           4 |          0 |          0 |       0 |        0 |        0 |        0 |                 v_rate := 0.10;           | 
           5 |          0 |          0 |       0 |        0 |        0 |        0 |             ELSIF p_income <= 100000 THEN | 
           6 |          1 |         24 |    6.84 |       24 |       24 |       24 |                 v_rate := 0.20;           | 
           7 |          0 |          0 |       0 |        0 |        0 |        0 |             ELSE                          | 
           8 |          0 |          0 |       0 |        0 |        0 |        0 |                 v_rate := 0.30;           | 
           9 |          0 |          0 |       0 |        0 |        0 |        0 |             END IF;                       | 
          10 |          1 |          0 |       0 |        0 |        0 |        0 |             RETURN v_rate;                | 
          11 |          0 |          0 |       0 |        0 |        0 |        0 |         END get_tax_rate;                 |

関数の行レベルのパフォーマンスデータの表示

plsql_profiler_show_funclist() と plsql_profiler_show_function() 関数を一緒に使用して、すべての関数内の各コード行の詳細なパフォーマンスデータをクエリできます。

SELECT * FROM plsql_profiler_show_funclist() F
CROSS JOIN LATERAL plsql_profiler_show_function(F.func_oid_list) C;

ステップ 6：HTML レポートの生成と表示

より直感的な分析のために、plsql_profiler_get_report() を使用して完全なレポートを HTML 形式で生成できます。

-- psql クライアントで、\o コマンドを使用して出力をファイルにリダイレクトします。
\o plsql_profiler_report.html
-- タプルのみモードを有効にして、クリーンな HTML コンテンツを出力します。
\t 
-- レポートを生成します。
SELECT plsql_profiler_get_report('My Performance Report');
-- リダイレクトを無効にします。
\o
-- タプルのみモードを無効にします。
\t

コマンドが実行されると、完全なレポートを含む HTML 文字列が返されます。この文字列を HTML ファイルにコピーし、ブラウザでファイルを開くと、詳細なパフォーマンス分析レポートが表示されます。

ステップ 7：リソースのクリーンアップ

-- 1. (オプション) 収集した分析データをリセットします。
SELECT plsql_profiler_reset();

-- 2. アナライザを無効にします。
SELECT plsql_profiler_disable();

-- 3. (オプション) 不要になった場合は、拡張機能を削除します。
DROP EXTENSION polar_plsql_profiler;

関数リファレンス

POLAR_PLSQL_PROFILER プラグインは、次のコア関数を提供します。

制御関数

plsql_profiler_enable()

説明：現在のセッションでパフォーマンスアナライザを有効にします。
構文：sys.plsql_profiler_enable() RETURNS bool
戻り値：アナライザが正常に有効化された場合は true、それ以外の場合は false の bool 値。

plsql_profiler_disable()

説明：現在のセッションでパフォーマンスアナライザを無効にします。
構文：sys.plsql_profiler_disable() RETURNS bool
戻り値：アナライザが正常に無効化された場合は true、それ以外の場合は false の bool 値。

plsql_profiler_reset()

説明：現在のセッションで収集されたすべてのパフォーマンス統計をクリアします。
構文：sys.plsql_profiler_reset() RETURNS void
戻り値：なし。

レポートおよび分析関数

plsql_profiler_show_funclist()

説明：アナライザ自身の関数を除く、呼び出されたすべての関数の呼び出しチェーンと全体的なパフォーマンスサマリーを表示します。
構文：sys.plsql_profiler_show_funclist() RETURNS TABLE(...)

戻り値：次のフィールドを含むテーブル。

フィールド	説明
`func_call`	テキスト形式の関数呼び出しチェーン。
`func_oid_list`	呼び出しスタック内の関数オブジェクト識別子 (OID) のリスト。
`call_count`	関数が呼び出された回数。
`us_total`	合計実行時間 (マイクロ秒)。
`us_declare`	宣言セクションの実行時間 (マイクロ秒)。
`us_children`	子関数の実行時間 (マイクロ秒)。
`us_self`	関数自体の実行時間 (マイクロ秒)。
`time_stamp`	関数呼び出しのタイムスタンプ。

plsql_profiler_show_function()

説明：指定された関数内の各コード行の詳細なパフォーマンス統計を表示します。
構文：sys.plsql_profiler_show_function(func_oid OID[]) RETURNS TABLE(...)
パラメーター：
パラメーター
説明
func_oid
詳細を表示する関数の OID の配列。この値は、plsql_profiler_show_funclist() 関数の func_oid_list 列から取得します。

戻り値：次のフィールドを含むテーブル。

フィールド	説明
`line_number`	ソースコード内の行番号。
`exec_count`	この行が実行された回数。
`total_time`	合計実行時間 (マイクロ秒)。
`percent`	この行が関数の合計時間に占める割合。
`avg_time`	1 回の実行あたりの平均実行時間 (マイクロ秒)。
`min_time`	この行の最小実行時間 (マイクロ秒)。
`max_time`	この行の最大実行時間 (マイクロ秒)。
`source_code`	この行のソースコード。
`time_stamp`	匿名ブロックの実行のタイムスタンプ。匿名ブロック以外の場合は `null` です。

plsql_profiler_get_report()

説明：完全なパフォーマンス分析レポートを HTML 形式で生成します。
構文：sys.plsql_profiler_get_report(IN title text DEFAULT 'PL/SQL PROFILER REPORT') RETURNS text
パラメーター：
パラメーター
説明
title
レポートのタイトル。このパラメーターはオプションです。デフォルト値は PL/SQL PROFILER REPORT です。
戻り値：完全なレポートを含む HTML 文字列である text 値を返します。

低レベルデータ取得関数

plsql_profiler_linestats_local()

説明：関数の実行回数やタイミングの詳細など、生の行レベルの統計を取得します。
構文：sys.plsql_profiler_linestats_local() RETURNS SETOF record

戻り値：次のフィールドを含むレコードのセット。

フィールド	説明
`func_oid`	呼び出しスタックを表す関数の OID の配列。
`line_number`	ソースコード内の行番号。
`exec_count`	この行が実行された回数。
`total_time`	合計実行時間 (マイクロ秒)。
`percent`	この行が関数の合計時間に占める割合。
`min_time`	この行の最小実行時間 (マイクロ秒)。
`max_time`	この行の最大実行時間 (マイクロ秒)。
`source`	この行のソースコード。
`time_stamp`	匿名ブロックのタイムスタンプ。

plsql_profiler_callgraph_local()

説明：関数の呼び出し回数やタイミングなど、生の関数コールグラフ情報を取得します。
構文：sys.plsql_profiler_callgraph_local() RETURNS SETOF record

戻り値：次のフィールドを含むレコードのセット。

フィールド	説明
`stack`	呼び出しスタックを表す関数の OID の配列。
`call_count`	この関数が呼び出された回数。
`us_total`	合計実行時間 (マイクロ秒)。
`us_declare`	宣言セクションで費やされた時間 (マイクロ秒)。
`us_children`	子関数で費やされた時間 (マイクロ秒)。
`us_self`	関数自体で費やされた時間 (マイクロ秒)。
`time_stamp`	関数呼び出しのタイムスタンプ。

plsql_profiler_func_oids_local()

説明：分析されたすべての関数の OID の配列を取得します。
構文：sys.plsql_profiler_func_oids_local() RETURNS oid[]
戻り値：分析されたすべての関数の OID を含む oid[] 配列を返します。

plsql_profiler_funcs_source()

説明：指定された関数 OID の配列のソースコードを返します。
構文：sys.plsql_profiler_funcs_source(func_oids oid[]) RETURNS SETOF record
パラメーター：
パラメーター
説明
func_oid
ソースコードを取得する関数の OID の配列。この値は、plsql_profiler_linestats_local() の func_oid 列から取得します。
戻り値：次のフィールドを含むレコードのセット。
フィールド
説明
func_oid
関数の OID。
line_number
ソースコード内の行番号。
source
この行のソースコード。

plsql_profiler_get_stack()

説明：関数 OID スタックを関数シグネチャの配列に変換します。
構文：sys.plsql_profiler_get_stack(stack oid[]) RETURNS text[]
パラメーター：
パラメーター
説明
stack
呼び出しスタックを表す関数の OID の配列。この値は、plsql_profiler_callgraph_local() の stack 列から取得します。
戻り値：関数シグネチャを含む text[] 配列を返します。

plsql_profiler_get_stack_formatted()

説明：関数 OID スタックをフォーマットされた呼び出しチェーンと OID リストに変換します。
構文：sys.plsql_profiler_get_stack_formatted(stack oid[]) RETURNS text[]
パラメーター：
パラメーター
説明
stack
呼び出しスタックを表す関数の OID の配列。この値は、plsql_profiler_callgraph_local() の stack 列から取得します。
戻り値：フォーマットされた関数呼び出しチェーンと OID リストを含む text[] 配列を返します。

よくある質問

アナライザを実行してもデータが表示されないのはなぜですか？

以下を確認してください。

ターゲットの PL/SQL コードを実行する前に、同じセッションで SELECT plsql_profiler_enable(); を実行します。アナライザは、有効化された後に現在のセッションで実行されるコードのみをプロファイルします。
分析データはセッションレベルであり、接続が中断されると失われます。データベースセッションが切断されてから再接続されたかどうかを確認してください。

このツールを本番環境で使用できますか？

アナライザはパフォーマンスオーバーヘッドを発生させるため、本番環境で継続的に有効にしないでください。一時的なパフォーマンス診断とチューニングにのみ使用してください。分析が終了したら、アナライザを無効にしてください。

パラメーター	説明
`func_oid`	詳細を表示する関数の OID の配列。この値は、`plsql_profiler_show_funclist()` 関数の `func_oid_list` 列から取得します。

パラメーター	説明
`title`	レポートのタイトル。このパラメーターはオプションです。デフォルト値は `PL/SQL PROFILER REPORT` です。