追跡と監視（FireDAC）

デバッグとサポート（FireDAC） への移動

このトピックでは、FireDAC の追跡機能および監視機能の使用方法を説明します。これらの機能は、FireDAC アプリケーションの主要なデバッグ ツールとなるもので、アプリケーションがデータベースとどう通信しているかを示します。

概要

FireDAC 追跡出力は、FireDAC アプリケーションとデータベース ソフトウェアとの通信の詳細なログです。これに記載されているのは、参照番号、時間、API 呼び出し、データベースに送信された SQL、データ交換とパラメータ値およびフィールド値、エラーと警告、データベース管理システム（DBMS）の環境レポートなどです。

FireDAC には、追跡結果を出力する方法が以下の 3 とおり用意されています。これらは、異なるコンポーネントと接続パラメータ MonitorBy の異なる値で制御されます。

コンポーネント	MonitorBy 値	説明
TFDMoniFlatFileClientLink	FlatFile	追跡結果をフラット テキスト ファイルに出力します。アプリケーションが終了すると、生成された追跡ファイルのリストが表示されます。
TFDMoniRemoteClientLink	Remote	追跡結果を FDMonitor ユーティリティに出力し、アプリケーションを監視できるようにします。FDMonitor は、追跡出力をアクティブにする前に実行されている必要があります。
TFDMoniCustomClientLink	Custom	追跡結果をカスタム イベント ハンドラに出力します。アプリケーションでは、OnOutput イベント ハンドラを使用してカスタム追跡出力を生成しなければなりません。

監視コンポーネントは、対応する追跡機能実装の単一インスタンスを参照しているシングルトンです。追跡出力が有効なすべての接続で同じ追跡コンポーネントが使用され、すべての接続について単一の出力が生成されます。

追跡の制御

接続の追跡出力を有効にするには、以下を行います。

1. フォームに TFDMoniXxxxClientLink コンポーネントをドロップします。
2. その Tracing プロパティを True に設定します。
3. MonitorBy=Xxx という接続定義パラメータを追加します。

MonitorBy パラメータは接続定義を特定の追跡方法に関連付けるもので、その定義の最初の接続が作成された後は読み取り専用になります。MonitorBy の設定は永続的でなければなりません。

MonitorBy=Xxx の最初の接続を開く前に、TFDMoniXxxxClientLink.Tracing プロパティを True に設定する必要があります。後で、すべての接続について追跡出力を一時的に無効または有効にするには、TFDMoniXxxxClientLink コンポーネントの Tracing プロパティを使用します。

メモ： TFDMoniXxxxClientLink は、データ モジュールやフォームの作成順序では、TFDConnection より先でなければなりません。

特定の接続の追跡出力を最初、無効にするには、MonitorBy=Xxx を使用します。特定の接続の追跡出力を一時的に無効または有効にするには、TFDConnection.ConnectionIntf.Tracing プロパティを設定します。ConnectionIntf は接続が確立された後でのみ使用可能であることに注意してください。

以下に例を示します。

 
FDMoniFlatFileClientLink1.Tracing := True;

with FDConnection1.Params do begin
  Clear;
  Add('DriverID=SQLite');
  Add('Database=c:\test.sdb');
  Add('MonitorBy=FlatFile');
end;

FDConnection1.Connected := True;
...
// disable trace output for connection
FDConnection1.ConnectionIntf.Tracing := False;
...
// enable trace output for connection
FDConnection1.ConnectionIntf.Tracing := True;

追跡内容

追跡内容を制御するには、TFDMoniXxxxClientLink.EventKinds プロパティを使用します。以下は追跡出力の例です。

     1385 15:47:14.093     >> Fetch [ATable="FDQA_FK_tab", Command="SELECT AF.fk_id, AF.id, AT1.f1, AT1.f2
 FROM FDQA_FK_tab AF LEFT JOIN FDQA_tabwithpk AT1 ON AF.fk_id=AT1.f1"]
     1386 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=0, Result=SQLITE_NULL]
     1387 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=1, Result=SQLITE_INTEGER]
     1388 15:47:14.093          . sqlite3_column_int64 [stmt=$0F16E6B8, iCol=1, AValue^=2]
     1389 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=2, Result=SQLITE_NULL]
     1390 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=3, Result=SQLITE_NULL]
     1391 15:47:14.093          . sqlite3_step [stmt=$0F16E6B8]
     1392 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=0, Result=SQLITE_INTEGER]
     1393 15:47:14.093          . sqlite3_column_int64 [stmt=$0F16E6B8, iCol=0, AValue^=2]
     1394 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=1, Result=SQLITE_INTEGER]
     1395 15:47:14.093          . sqlite3_column_int64 [stmt=$0F16E6B8, iCol=1, AValue^=3]
     1396 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=2, Result=SQLITE_INTEGER]
     1397 15:47:14.093          . sqlite3_column_int64 [stmt=$0F16E6B8, iCol=2, AValue^=2]
     1398 15:47:14.093          . sqlite3_column_type [stmt=$0F16E6B8, iCol=3, Result=SQLITE_TEXT]
     1399 15:47:14.093          . sqlite3_column_text [stmt=$0F16E6B8, iCol=3, bytes=4]
     1400 15:47:14.093          . sqlite3_step [stmt=$0F16E6B8]
     1401 15:47:14.093          . profile [SQL="SELECT AF.fk_id, AF.id, AT1.f1, AT1.f2
 FROM FDQA_FK_tab AF LEFT JOIN FDQA_tabwithpk AT1 ON AF.fk_id=AT1.f1", time=0]
     1402 15:47:14.093     << Fetch [ATable="FDQA_FK_tab", Command="SELECT AF.fk_id, AF.id, AT1.f1, AT1.f2
 FROM FDQA_FK_tab AF LEFT JOIN FDQA_tabwithpk AT1 ON AF.fk_id=AT1.f1", RowsAffected=2]

上記で、

• 先頭の数字（1385 ～ 1402）は行番号で、行を正確に参照するのに使用できます。
• タイムスタンプは、その行が生成されたときのローカル時刻で、パフォーマンスを測定するのに使用できます。
• 以下のパラメータはコマンドの SQL テキストなどの情報を示します。
  • >> Xxxx -- FireDAC 操作の開始を示します。
  • << Xxxx -- FireDAC 操作の終了を示します。
• sqlite3_xxx -- FireDAC 操作を実行するために行われた DBMS API 呼び出し（この例では SQLite）。

出力の制御

出力を制御するコンポーネントがいくつかあります。

フラット ファイル出力

TFDMoniFlatFileClientLink コンポーネントはフラット テキスト ファイル出力を制御します。デフォルトでは、追跡ファイルはお使いのシステムの TEMP フォルダに自動的に生成されます。FireDAC アプリケーションの終了時に、生成された追跡ファイルのリストが表示されます。

出力を制御するには、以下のプロパティを使用します。

• FileName -- 追跡ファイルの名前です。環境変数（$(<変数名>)）を使用できます。デフォルト名は $(TEMP)\traceN.txt です。
• FileEncoding -- 追跡ファイルのエンコーディングです。デフォルトのエンコーディングは ANSI です。
• FileAppend -- これが True の場合は、既存の追跡ファイルに追加されます。そうでない場合は、新しく実行するたびに既存の追跡ファイルが上書きされます。
• FileColumns -- テキスト ファイルに記載する列です。

リモート出力

TFDMoniRemoteClientLink コンポーネントは、リモート トレース出力を制御します。 FDMonitor ユーティリティを使用すると、トレース出力を見ることができます。 FireDAC は TCP/IP をトレース用トランスポートとして使用します。つまり、FDMonitor とアプリケーションはネットワーク内の異なるシステムで動作できるということです。 このことは、macOS 開発の場合にも当てはまり、アプリケーションが Mac で動作し、FDMonitor は Windows マシン上で動作することができます。

出力を制御するには、以下のプロパティを使用します。

• Host -- FDMonitor が動作するマシンの IP アドレスです。デフォルトは localhost です。
• Port -- FDMonitor がリスンする IP ポートです。デフォルトは 8050 です。
• Timeout -- FDMonitor への接続を確立するまでに許容される最長時間（ミリ秒単位）です。

カスタム出力

TFDMoniCustomClientLink コンポーネントを使用すると、カスタム追跡出力を生成できます。さらに言えば、アプリケーションで OnOutput イベント ハンドラを定義しなければなりません。

メモ： OnOutput イベント ハンドラでは Application.ProcessMessages を呼び出さないようにします。これを呼び出すと、パフォーマンスが著しく低下し、その結果、問題が発生する場合があるからです（これらの問題は、サポートされていない FireDAC の再入が起こる可能性があることに起因するものです）。

監視

FDMonitor ユーティリティでは、FireDAC オブジェクトの状態の監視もサポートしています。開発者はこの機能を使用して、独自のオブジェクトの監視を可能にすることができます。詳細については、FireDAC\Samples\Moni Layer\Main デモを参照してください。

SQL コマンド テキストの確認

以下の追跡機能を使用すると、データベースへの送信時の SQL コマンド テキストを確認できます。

• TFDQuery.Text -- データベースへの送信時の SQL コマンド テキストを返します。
• EFDDBEngineException.SQL、Params -- 例外が発生した SQL コマンド テキストを返します。

データセット行の確認

以下の方法のいずれかを使って、データセット行をダンプすることができます。

• DataSet.GetRow.DumpRow(True) -- すべてのフィールド名とすべてのフィールド値を含め、現在のデータセット行を表すテキストを返します。
• DataSet.GetRow.DumpRow() -- すべてのフィールド値を含め、現在のデータセット行を表すテキストを返します。
• DataSet.Table.Rows[i].DumpRow() -- ランダムなデータセット行を表すテキストを返します。

関連項目

• DBMS 環境レポート

サンプル

• FireDAC MoniLayerClients サンプル