Pings エンドポイント
GET
/api/v1/pings特定の VPS Agent が自分のネットワーク位置から実行したプローブ履歴を読み取ります。このソースは Cloudflare の能動チェックや外部 Latency Agent とは独立しています。
ターゲットプロトコル
管理 UI は既存のターゲットフィールドを保持します。Agent v1.0.44 以降、スキームがプローブ方式を選択します。
| 構文 | プロトコル | 成功条件 |
|---|---|---|
host:port | TCP | 1 秒以内に TCP 接続 |
tcp://host:port | TCP | 1 秒以内に TCP 接続 |
http://host/path | HTTP | 1 秒以内に 200-399 応答 |
https://host/path | HTTPS | 1 秒以内に 200-399 応答 |
ターゲットに HTTP のユーザー名やパスワードを含めてはいけません。Agent は tcp,http を公表します。1.0.44 は新しい icmp:// ターゲットを受け付けず、既存の ICMP ターゲットも配信されません。
クエリパラメータ
| パラメータ | 必須 | 既定 | 目的 |
|---|---|---|---|
agent_id | はい | 空 | プローブを実行する Agent |
hours | いいえ | 24 | 既定最大 72 時間、デプロイ上限 168 時間 |
max_points_per_target | いいえ | 360 | 通常カーブのターゲットごとポイント数。非正はフォールバック、ハード上限 2000 |
format | いいえ | row | series はターゲットごとのコンパクト系列を返す |
include_loss | いいえ | 0 | 1 はウィンドウ内の全生ロスイベントを無損失で返す |
bash
curl -fsSL 'https://YOUR-API/api/v1/pings?agent_id=vps-a&hours=6&format=series&include_loss=1'レスポンスフィールド
| フィールド | 目的 |
|---|---|
targets[] | 有効なターゲット ID・名前・色 |
pings[] | 上限付き行履歴。format=series では空 |
series | ターゲットごとの上限付きコンパクトカーブ |
ping_stats | ダウンサンプリング前の生サンプルからの合計・成功・ロス率 |
pings_raw_count | ダウンサンプリング前のポイント数 |
pings_downsampled | 通常カーブがダウンサンプリングされたか |
ping_interval_sec | 現在のグローバルプローブ間隔 |
loss_series | include_loss=1 時の無損失ロス runs |
loss_events_raw_count | loss_series が表す生ロスイベント数 |
source | 現在の履歴ソース |
loss_series[] は { target_id, t0, runs } を使います。各 run は [start_delta, step, count] で、タイムスタンプは t0 + start_delta + step * index（index は 0 から count - 1）です。まばらなロスも破棄されません。内蔵フロントエンドはこのレイヤーを描画しなくなり、ping_stats でターゲットごとのロスを表示します。
失敗ポイントの latency_ms は null です。0 ms と解釈しないでください。R2 は生テレメトリを正の履歴として保持します。任意の時系列エクスポートはこのエンドポイントを変えず、エクスポート失敗が Agent ACK や R2 アーカイブをブロックすることもありません。
表示のアドバイス
- 凡例は
targets[]の名前を使い、データは ID で紐付けます。 - 遅延カーブは上限付き
series、ターゲットごとのサマリーはping_statsを使います。 - 完全なロスイベントが必要なら
include_loss=1でloss_seriesを読み取ります。 - Agent オフライン中に新しいプローブがないのは想定どおりです。
- Pings を他のソースとラベルなしカーブに統合しないでください。