開発者向けHQbird
アプリケーション開発者向け
最初に最適化すべきクエリはどれか? エラーを起こしたコードはどれか? 競合でレコードを保持しているのは誰か? エージェントがサーバー上でトレースと統計から答えを収集します。開発者はブラウザでそれらを確認でき、サーバーにログインする必要はありません。
- 1 分 トレースファイル
- 1 日 3 ウィンドウ パフォーマンスレポート
- プラン別 クエリのグループ化
- 15 分 競合の検索
- REST スクリプトと CI 向けのローカル API
trace · process_traces · perf report
パフォーマンスレポート
エージェントは常にトレースセッションを開いたままにします。毎分、出力をファイルに圧縮し、各クエリの合計を計算します。ウィンドウが終了すると、エージェントは分単位のデータをレポートにまとめます。最も遅いクエリと、フェッチ、読み取り、書き込みの量が多いクエリです。各クエリには実行回数が表示されます。
- 1トレースセッションfbtracemgr が常時実行され、ウォッチドッグが失われたセッションを再起動します
- 2分単位ファイル1 分ごとに圧縮されたトレース出力
- 3分単位の合計各クエリごと: 実行回数、時間、フェッチ、読み取り、書き込み、マーク
- 4ウィンドウレポートウィンドウ終了後 5 分以内。各ランキングに最大 20 クエリ
- 5✓ HQ MonitorPerf Report ページ。ヘルスレポートからのリンク
プラン別にグループ化する理由
プログラムが値を SQL テキストに直接埋め込むと、値ごとに新しいテキストが生成されます。ある実際のケースでは、異なるテキストの数が毎分 204 から 83,825 に増加しました。何千もの「異なる」クエリは、実際には 1 つのプランを持つ 1 つのクエリです。そのため、エージェントはデフォルトでクエリをキーでグループ化します。キーは、コメントを除いた SQL の最初の 10 文字と実行プランです。プランのないクエリは完全なテキストを保持します。モードはエージェント設定の「Perf group by」フィールドで変更できます。プラン別または完全な SQL テキスト別です。テキスト別では、ファイルとレポートがはるかに大きくなります。以下の例でモードを切り替えて、ランキングを比較してください。
1 分間のクエリ
フェッチ数によるランキング
| レポートテーブル | 表示内容 |
|---|---|
| 実行時間別トップ SQL | 最も遅い実行: 時間とレコード数。 |
| フェッチ、読み取り、書き込み別トップ SQL | ウィンドウの合計: 実行回数、時間、フェッチ、読み取り、書き込み、マーク。ウィンドウ全体に占める割合。実行ごとの平均と最大。 |
| プロセスとアドレス | プログラム別およびクライアントアドレス別の負荷: 接続数、時間、異なるプランとクエリの数。 |
| クエリ行 | 完全な SQL、PLAN、パラメータ、テーブル別統計: natural、index、update、insert、delete、backout、purge、expunge。 |
| タブ内の 10 のランキング | 実行時間、頻度、合計時間、フェッチ、読み取り、書き込み、プラン、タグ、プロシージャ、トリガー。各メトリクスについて、値の分布が表示されます。 |
| サンプル実行 | 実行された時刻、どのクライアントがどのアドレスから、どのデータベースで実行したか。実行がエラーで終了した場合はそれが表示され、各クエリには失敗した実行のカウンターがあります。 |
| 時間別の実行 | ウィンドウの各時間帯にクエリが何回、どれだけの時間実行されたか。 |
| データベース | サーバーのデータベース別および各クエリの主要データベース別の合計。 |
比較、履歴、オンデマンドレポート
ウィンドウレポートは「今日何が重かったか」という問いに答えます。3 つの新しい機能は「何が変わったか」「この時間に何が起きたか」という問いに答えます。
- 2 つのウィンドウの比較2 つのレポートを並べて表示: どのクエリが遅くなったか、どれが現れ、どれが消えたか。
- 30 日間のクエリ履歴1 つのクエリの時間と実行回数がウィンドウごとにどう変化したか。
- データベースによるフィルター1 つのデータベースのみのレポート。データベースページのリンクからレポートページへ移動します。
- その分のトレースへレポート内のクエリから、それが実行された分のトレースへ移動します。
- オンデマンドレポートBuild report… ボタンで、最大 24 時間までの任意の範囲のレポートを作成します。フィルター: データベース、最小実行時間、プログラム。エージェントはこのようなレポートを一度に 1 つ作成し、最後の 20 件を保持します。
- 検索とダウンロードクエリテキスト用の検索フィールド。レポートのソースファイルをダウンロードできます。
- 不完全なレポートはマークされる一部のトレースファイルがまだ届いていない場合、レポートは不完全としてマークされます。レポートは各ランキングのトップのみを保持するため、ページには「実行されなかった」ではなく「ランキングにない」と表示されます。
- プロシージャとトリガーこれらのランキングは、トレース設定でプロシージャとトリガーの終了のログ記録を有効にすると埋まります。デフォルトでは、このログ記録はオフです。
- ヘルスレポートからPerf report ボタンで該当するウィンドウが開きます。クエリ行はマークされ、最初の行はすでに展開されています。
- クエリとテーブルgstat統計の「クエリ」タブでは、クエリが読み取るテーブルとインデックスがクエリにリンクされます。
- データベースチャートの1分1分をクリックすると、その1分間のトレースとすべての接続から負荷の高いクエリが表示されます。
- SQLのコピーパラメータ付きでもなしでも、自分のツールに直接貼り付けられます。デモモードではボタンは非表示になります。
trace · エラー
クライアントデータ付きのSQLエラー
ユーザーが「プログラムでエラーが出た」と言います。エラーページには、トレースからの各Firebirdエラーが表示されます: 時刻、接続、データベース、テキスト、クライアント。プログラム名、アドレス、Firebird関数があれば、コード内のエラーを簡単に見つけられます。
トレース内のエラーブロック
エラーページの行
- 同じエラーは1行に1分、データベース、エラー種別ごとに1行で、×Nの件数が付きます。ヒントには最初と最後の時刻、および接続数が表示されます。
- フィルターテキスト、データベース、プログラム、アドレス、関数によるIncludeとExclude。プログラムやアドレスをクリックすると、そのエラーのみに絞り込まれます。
- CSVエクスポートフィルター適用後のすべての行を、BOM付きUTF-8で出力: Excelでファイルを開くとすぐに列に分かれます。
- プログラムがない場合多くのJDBCおよび.NETドライバーはプログラム名を送信しません。その場合、クライアントの行は短くなります。
trace_monitor_conflicts · find_deadlocks
競合とデッドロック
「update conflicts with concurrent update」というエラーだけではほとんど何も分かりません。もう一方のトランザクションが何をしたのかを知る必要があります。そのために、エージェントはデータ変更とエラー用に設定された2つ目のトレースセッションを保持します。15分ごとに競合を検索し、レポートを作成します。
レポートの読み方
左側は競合が発生した分の一覧です。各グループは競合を引き起こした1つのトランザクションで、トランザクション番号とエラー時刻が表示されます。
左の列にはエラーが表示されます: 接続、プログラム、Firebirdコード、失敗したクエリ。右の列には競合するトランザクションの成功したクエリが表示されます: 時刻、接続、トランザクション番号、プログラム。各クエリにはSQL、パラメータ、統計、テーブルが付きます。
ページのアドレスには日付と分が保持されます。リンクを同僚に送ることができます。
| パラメータ | デフォルト | 意味 |
|---|---|---|
| 競合検索 | 15分ごと | 最後の1分はスキップされます: トレースがまだ書き込み中です。 |
| 検索の深さ | 3時間 | もう一方のトランザクションのクエリを検索する際に、競合より前のどのくらいの履歴を調べるか。 |
| 生トレースの保持 | 6時間 | 競合セッションの生ファイルがサーバー上に溜まりません。レポートは保持され、HQ Monitorに送信されます。 |
gstat · インデックス · メタデータ
データベースの変化
エージェントは1日1回、完全なgstat統計を取得します。HQ Monitorはファイルを解析します: テーブルとインデックスのサイズ、レコードバージョン、BLOB、インデックスの深さ。「分析と推奨事項」タブには、何が問題で何をすべきかが表示されます。
| タブ | 開発者に何をもたらすか |
|---|---|
| テーブル | データ、インデックス、BLOBのサイズ、レコード数、レコードバージョン数、および1レコードの最大バージョン数。 |
| インデックス | 深さ、ページ数、一意値数、重複数。深さ4は黄色の行、5以上は赤色。 |
| クエリとリンク | どのクエリがテーブルやインデックスを読み取っているか。スナップショットに近い時刻のパフォーマンスレポートからのデータ。 |
| トレンド | 5、10、20、30個のスナップショットの比較。変化のしきい値は10%、2%、0.5%。3つ以上のスナップショットからの「+25%」予測。 |
| エクスポート | 計測値を含むJSONと、完全な分析を含むExcel。 |
- インデックス統計デフォルトではオフ。エージェント設定でオンにします。オンにすると、エージェントは6時間ごとに非アクティブなインデックスと選択性の低いインデックスをカウントします。リストア後に構築されていないインデックスは、ヘルスレポートで重大な問題となります。
- 増加予測データベーステーブルの「+25%」チップは、最も急速に増加しているテーブルまたはインデックスを示し、予測を開きます。
- スキーマのエクスポートエージェントは
isql -xでデータベースのメタデータをエクスポートし、日付ごとにアーカイブを保持します。 - メタデータの追跡デフォルトではオフ。エージェント設定でオンにします。オンにすると、エージェントは6時間ごとに新しいスキーマエクスポートを前回のものと比較し、スキーマが変更された日時を記録します。
LWM · MON$ · クライアント
接続: 長時間トランザクションとクライアントバージョン
忘れられたトランザクションが1つあるだけで、データベース全体が遅くなります。レコードバージョンが蓄積し、ガベージコレクションが停止します。
エージェントは毎分、トランザクションカウンターと接続データを書き込みます。データベースのチャートでは、トランザクションが長時間開いたままになるとNext − OATが増加します。その分の接続テーブルをAct.Tranでソートすると、トランザクションを保持しているプログラム、アドレス、プロセスがわかります。カウンターの詳細はサーバーヘルスページにあります。
エージェントは1日1回、どのクライアントライブラリがデータベースに接続しているか、それぞれの接続数を読み取ります。「Not detected. Old version?」という行は通常、古いクライアントライブラリを意味します。
- MON$メトリクス1時間ごと: プログラム別のメモリ、メモリ使用量が最も多い5つの接続、負荷が最も高い5つの接続。
- 誤検知のない古いクライアント「古いクライアント」の検出はfbclientライブラリのみをカウントします。fbclientなしで動作するドライバはカウントされません。
- レポート内の長時間トランザクションヘルスレポートは長時間トランザクションとNext − OATの増加をマークします。検出結果にはユーザー、プログラム、アドレスが示され、切断するためのコマンドが用意されています。
Local API · Prometheus · HQbird MCP
スクリプト、CI、AIアシスタント
HQ Monitorで表示されるすべての情報は、独自のツールから利用できます。エージェントのLocal APIはループバックでのみ待ち受け、各リクエストにはBearerトークンが付きます。重いジョブは非同期で実行されます。レスポンスは操作番号を返し、それを使ってステータスを読み取ります。エージェントは、サーバーを変更する各リクエストと、各401または403の拒否を監査ログに書き込みます。読み取りリクエストはログには記録されません。
# Local APIポート = 10000 + Firebirdポート: ここではFirebirdが3055を使用するため13055 # サーバーステータス: ヘルスレポートと同じスナップショット curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # 最新のパフォーマンスレポートと最新の競合レポート curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest # CIで移行前にバックアップを実行し、結果を待つ curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \ http://127.0.0.1:13055/v1/jobs/vbackup/run curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
| パス | 得られるもの |
|---|---|
/v1/status | サーバーステータスのスナップショット。全体またはセクション別(例: バックアップ)。 |
/v1/databases | アクティブなデータベースの一覧。 |
/v1/artifacts/… | エージェントデータ: 毎分のLWM (Light-weight Monitoring)、gstat、インデックス統計、メトリクス、最新のスキーマエクスポート、トレースレポート。 |
/v1/jobs/{job}/run | ジョブの実行: バックアップ、リストア、スイープ、データベースチェック、インデックス統計の再計算、SQLスクリプト。同じキーでの繰り返しはジョブを二重に実行しません。 |
PrometheusメトリクスはLocal APIを経由しません。独自のアドレスを持ちます: デフォルトでは127.0.0.1、ポート25000 + Firebirdポート。独自のBearerトークンを使用します。エクスポートはデフォルトではオフ。エージェント設定でオンにします。メトリクス: LWM、CPUとメモリ、ディスク、OSの制限、一時ファイル。
IDE内のAIアシスタント
HQbird MCPはFirebirdとエージェントデータをClaude Code、Cursor、Codex、その他のMCPクライアントに接続します。アシスタントはエージェントレポートを参照し、人間の管理下でデータベースを操作します。危険な操作は人間が確認します。
プランとインデックス
クエリプランとインデックスのアドバイス。インデックス作成後のプラン再チェック付き。実行前のクエリのコンパイルチェック。
2つのデータベースを比較
スキーマとデータの差分。たとえば開発環境とテスト環境の間など。
計画、確認、ロールバック
計画、1回の確認、ロールバック計画を伴う移行。