Insight Open APIs
はじめに
アナライザーインスタンスにOpen APIをインストールすることで、レイテンシ、スループット、信頼性に関連するリアルタイム測定値と主要業績評価指標(KPI)の抽出が可能になります。
APIは、プロトコルごとのレイテンシ測定、ネットワークおよびアプリケーションレイテンシレベルの集約KPI、変動性や安定性などの新しいネットワーク品質修飾子など、既存のビジュアルダッシュボードで利用可能な選択されたデータを抽出できます。
API出力データは、指定されたQoSAgent-Reflectorペアに対してJSON形式で提示されます。結果は他の外部システムに簡単に統合できます。
A) Connectivity Insight APIを使用すると、ユーザーはAgentIDを使用して特定のQoSAgentに関する接続性能データをアナライザーインスタンスに問い合わせることができます。リクエストは、
B) Throughput Insight APIを使用すると、ユーザーはLifbeプロトコルを使用してリアルタイムスループット測定をアナライザーインスタンスに問い合わせることができます(設定および有効化されている場合)。 このAPIを使用して、Mbps単位のダウンロードおよびアップロード結果と関連するジッター結果を取得します。
C) Latency Insight APIは、特定のプロトコルと特定のエージェントのレイテンシ測定値を、秒単位で設定されたユーザー指定の時間範囲で取得するために使用できます。
D) Geoloc Insight APIは、測定された最新の平均レイテンシとそのGPS形式の地理座標(利用可能で設定されている場合)をクエリするために使用されます。オプションのtime_rangeクエリパラメータを/api/v1/geolocエンドポイントに追加することで、ユーザーは履歴地理位置情報データを取得する時間帯を秒単位で指定できます。
E) Twamp Insight APIは、指定されたQoSAgentに対してTWAMPプロトコル(RFC 5357)を使用して測定された最新の詳細なレイテンシレベルをクエリするために使用できます。レイテンシ結果は、順方向レイテンシ(ミリ秒)、逆方向レイテンシ(ミリ秒)、処理レイテンシ(ミリ秒、つまりReflector内で費やされた時間)に分割されます。
F) Forecast Insight APIは、統計ベースの平均と予測を使用した最新の予測測定値を提供します。
G) Radio Insight APIは、最新の無線/セルラー測定値を提供します。
H) Networks APIは、アナライザー上のすべてのcustomer_id / networksを提供します。
I) Agents APIは、customer_idに接続されているすべてのQoS-Agentを提供し、IDのみを含めることも、メタデータも含めることもできます。
J) Anomalies Insight APIは、詳細な異常メトリクスとパターン分析を使用して、プロトコル全体のネットワーク異常を検出して報告します。
K) Performance Trends APIは、時間の経過に伴うエージェントのパフォーマンストレンドを分析し、現在のパフォーマンスを過去のベースラインと比較して、劣化パターンを特定します。
L) Health Report APIは、エージェントランキング、パフォーマンス分布、および実用的な推奨事項を含む包括的なネットワークヘルスレポートを生成します。
M) Agent Rankings APIは、パフォーマンスメトリクスとトレンドによってすべてのエージェントをランク付けし、ネットワーク全体の上位および下位のパフォーマーを特定します。
N) Correlation Analysis APIは、エージェント間の相関パターンを検出して、複数の場所に同時に影響を与えるネットワーク全体の問題を特定します。
O) Degradation Alerts APIは、指定された期間にわたって設定可能なしきい値を超えるパフォーマンス低下を示すエージェントを積極的に識別します。
P) iPerf Throughput Insight APIは、特定のQoSAgentに対するiPerf測定からTCP/UDPスループットを返します。
APIでは、アナライザーインスタンスでポート12099を開いて保護する必要があります。
使用方法
認証
APIはAPIキー認証を使用します。すべてのリクエストでx-api-keyヘッダーにAPIキーを含めてください。
x-api-key: your_api_key_here
コンテナログを調べることでAPIキーを取得できます。
docker logs <api_container_ID>| grep "API Key:"
A) Connectivity Insight API
結果は複数の時間窓を使います。プロトコル別レイテンシは直近10秒、ジッター/変動性/安定性は直近5分、QoEは直近30秒、スループットは直近12時間、メタデータと期待値は直近1週間です。
/api/v1/ciエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータを使用してエージェントの測定値を確認できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/ci?agent_id=<agentID>&customer_id=<customerID>
サンプル出力:
{
"CustomerID": "0",
"AgentID": "0",
"KPIs": {
"tcpMs": 8.94,
"udpMs": 9.53,
"httpMs": 9.09,
"httpsMs": 18,
"icmpMs": 9.2,
"twampMs": 9.45,
"downloadThroughputMbps": 1383.58,
"uploadThroughputMbps": 950.06,
"networkLatencyMs": 9.32,
"applicationLatencyMs": 11.39,
"packetLossRatePercent": 0,
"jitterMs": 6.1,
"volatilityPercent": 46.2,
"networkStabilityPercent": 65.5,
"connectivityHealth": "Warning",
"qualityOfExperience": 4.921,
"expectedLatencyMS": 40,
"expectedStabilityPercent": 98,
"expectedPacketLossPercent": 0.1
},
"Attributes": {
"time": "2025-03-26T14:01:23.305Z",
"agentName": "GenericQoSAgent",
"hardware": "Not-Applicable",
"networkName": "OutScale-Network",
"networkType": "Outscale",
"gpsPos": "48.864716,2.349014",
"details": "Generic QoSAgent preinstalled with OMI",
},
"APInotes": {
"comment": "Results from LatenceTech ConnectivityInsight API version 2.1",
"documentation": "Refer to docs.latence.ca for API details and data structure"
}
}
新しい接続性インサイト v2
GET /v2/ci?customer_id={customer_id}&agent_id={agent_id}
v2エンドポイントは、期待値、volatilityPercent、networkStabilityPercent、connectivityHealth、およびメタデータを提供しません。
これは、/v1/ciの軽量版として作成されました。
B) Throughput Insight API
LIFBE の最新値を返します。スループットとジッターは直近2時間、パケットロスは直近12時間です。
/api/v1/lifbeエンドポイントで使用されます。
Lifbeプロトコルを使用したスループット測定のリアルタイムデータを、agent_idおよびcustomer_idパラメータを使用して表示できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/lifbe?agent_id=<agentID>&customer_id=<customerID>
サンプル出力:
{
"agentID": "1",
"time": "2024-05-17T15:00:04.735Z",
"lifbeDownload": 542.48,
"lifbeUpload": 49.89,
"jitterDownload": 1.23,
"jitterUpload": 3.13,
"networkInterface": "MOBILE",
"networkType": "MOBILE_5G"
}
C) Latency Insight API
time_range(秒)または chosen_time が必須です。デフォルト時間窓はありません。
/api/v1/latencyエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータに加えて、クエリに3つのオプション引数を追加することで、特定のエージェントの特定のプロトコルの測定値をユーザー指定の時間範囲で確認できます。
1) protocol (tcp, udp, https, httpss, icmp, twamp)
2) time_range (秒単位)
3) chosen_time
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/latency?agent_id=<agentID>&customer_id=<customerID>&protocol=tcp&time_range=400
サンプル出力:
[
{
"agentID": "1",
"time": "2024-05-17T15:01:26.183Z",
"measurement": "tcp_result",
"value": 15.61
},
{
"agentID": "1",
"time": "2024-05-17T15:01:28.215Z",
"measurement": "tcp_result",
"value": 15.233
}
]
オプション: protocolパラメータはオプションです。設定しない場合、すべてのプロトコルが表示されます。
オプション: chosen_timeパラメータを使用すると、指定された期間のデータをクエリできます。形式はstart_time,end_time(例: 2025-05-30T10:00:00Z,2025-06-15T17:00:00Z)です。
time_rangeとは併用しないでください。
指定する時刻はUTC、またはアナライザーに設定されたタイムゾーン(デフォルトはUTC)である必要があります。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/latency?customer_id=<customerID>&agent_id=<agentID&chosen_time=2025-07-07T16:12:26Z,2025-07-07T16:12:34Z
サンプル出力:
[
{
"CustomerID": "0",
"agentID": "9",
"time": "2025-07-07T16:12:25.000Z",
"tcp": 46.364,
"udp": 48.355,
"http": 49.572,
"https": 96.752,
"twamp": 47.791,
"icmp": 48.5
},
{
"CustomerID": "0",
"agentID": "9",
"time": "2025-07-07T16:12:30.000Z",
"tcp": 48.233,
"udp": 48.005,
"http": 47.985,
"https": 96.531,
"twamp": 47.812,
"icmp": 48.5
}
]
D) Geoloc Insight API
デフォルトでは直近1分を使用し、time_range(秒)指定時はその期間を使用します。
モバイルアプリケーション(または地理位置情報取得が有効なモデム/CPE)を使用してGPSデータをアナライザーに送信すると、レイテンシの現在の状態と以前の位置を含む履歴データを確認できます。
/api/v1/geolocエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータと、履歴データを取得するためのオプションのtime_range(秒単位)を追加できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/geoloc?agent_id=<agentID>&customer_id=<customerID>
履歴データの場合:
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/geoloc?agent_id=<agentID>&customer_id=<customerID>&time_range=400
サンプル出力:
{
"agentID": "50",
"time": "2024-05-17T15:01:20Z",
"altitude": "39.1",
"latitude": "45.4961001",
"longitude": "-73.5619866",
"applicationLatency": 10.213
}
E) Twamp Insight API
直近5分の TWAMP デルタ最新値を返します。
このAPIは、指定されたQoSAgentに対してTWAMPプロトコル(RFC 5357)を使用して測定された最新の詳細なレイテンシレベルをクエリするために使用できます。レイテンシ結果は次のとおりです。 - TwampFwdDeltaMs = TWAMP順方向デルタ(つまり、QoSAgent -> Reflector間のレイテンシ)、ミリ秒単位 - TwampRevDeltaMs = TWAMP逆方向デルタ(つまり、Reflector -> QoSAgent間のレイテンシ)、ミリ秒単位 - TwampProcDeltaMs = TWAMP処理デルタ(つまり、Reflector内で発生するレイテンシ)、ミリ秒単位
/api/v1/twampエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/twamp?agent_id=<agentID>&customer_id=<customerID>
サンプル出力:
{
"agentID": "12",
"time": "2024-06-21T18:56:58.512Z",
"TwampFwdDeltaMs": 0.32,
"TwampRevDeltaMs": 0.94,
"TwampProcDeltaMs": 0.18,
}
F) Forecast Insight API
予測レイテンシは直近5分を使用し、予測区間と信頼水準は直近10分のレイテンシデータから算出します。
このAPIは、統計ベースの平均と予測を使用した最新の予測測定値を提供します。
/api/v1/forecastエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/forecast?agent_id=<agentID>&customer_id=<customerID>
サンプル出力:
{
"agentID": "1",
"time": "2024-06-21T18:56:58.512Z",
"projectedLatencyMs": 1.5,
"forecastingIntervalMs": 3.28,
"confidenceLevel": 0
}
G) Radio Insight API
最新スナップショットは直近10秒を使用します。time_range または chosen_time 指定時はその期間のデータを返します。
このAPIは、最新の無線/セルラー測定値を提供します。
/api/v1/radioエンドポイントで使用されます。
agent_idおよびcustomer_idパラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/radio?agent_id=<agentID>&customer_id=<customerID>
サンプル出力:
{
"CustomerID": "0",
"agentID": "1",
"time": "2025-02-04T17:12:56.062Z",
"networkName": "Bell",
"networkType": "4G LTE",
"cellID": "40",
"SINR_dB": "2.147489",
"RSSI_dBm": "-63",
"RSRP_dBm": "-10",
"RSRQ_dB": "-94"
}
オプション: chosen_timeパラメータを使用すると、指定された期間のデータをクエリできます。形式はstart_time,end_time(例: 2025-05-30T10:00:00Z,2025-06-15T17:00:00Z)です。
指定する時刻はUTC、またはアナライザーに設定されたタイムゾーン(デフォルトはUTC)である必要があります。
curl -H "x-api-key: your_api_key_here" -k https://<analyzer_IP>:12099/api/v1/radio?customer_id=<customerID>&agent_id=<agentID&chosen_time=2025-07-07T16:12:26Z,2025-07-07T16:12:34Z
サンプル出力:
[
{
"CustomerID": "0",
"agentID": "12",
"time": "2025-07-08T15:21:07.94Z",
"ECIO_dB": "0",
"PCI": "908",
"RSRP_dBm": "-101",
"RSRQ_dB": "-13",
"RSSI_dBm": "0",
"SINR_dB": "15.5",
"cellID": "22938075680",
"networkName": "TELUS",
"networkType": "5G"
},
{
"CustomerID": "0",
"agentID": "12",
"time": "2025-07-08T15:21:17.932Z",
"ECIO_dB": "0",
"PCI": "908",
"RSRP_dBm": "-101",
"RSRQ_dB": "-13",
"RSSI_dBm": "0",
"SINR_dB": "16",
"cellID": "22938075680",
"networkName": "TELUS",
"networkType": "5G"
},
]
H) Networks API
直近1時間で観測された customer ID を一覧で返します。
このAPIは、アナライザーのcustomer_idを提供します。
/api/v1/networksエンドポイントで使用されます。
パラメータは不要です。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/networks
サンプル出力:
{
"count": 1,
"customerId": [
"0"
]
}
I) Agents API
直近20秒でアクティブなエージェントを返します。メタデータ(要求時)は直近1週間を使用します。
このAPIは、アナライザーのcustomer_idを提供します。
/api/v1/agentsエンドポイントで使用されます。
customer_idパラメータと、各エージェントのメタデータも受信するためのオプションのmetadata=trueを追加できます。
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/agents?customer_id=<customer_id>&metadata=true
サンプル出力:
{
"CustomerID": "0",
"count": 1,
"agents": [
{
"id": "9",
"name": "Montreal ref",
"networkName": "AzNet",
"networkType": "Azure Server Network",
"hardware": "Azure Server",
"details": "Azure Agent uses for Testing plateform",
"gpsPosition": "-43.8121,78.3522"
}
]
}
J) Anomalies Insight API
time_range または chosen_time が必須です。レイテンシは30秒単位で集計されます。
このAPIは、異常MAD(中央絶対偏差)、パケットドロップ、レイテンシスパイク、異常分布パターンなどの詳細なメトリクスを含む、プロトコル全体のネットワーク異常を検出して報告します。
/api/v1/anomaliesエンドポイントで使用されます。agent_id、customer_id、オプションのprotocol(tcp, udp, http, https, icmp, twamp)、およびtime_range(秒単位)パラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/anomalies?agent_id=<agentID>&customer_id=<customerID>&protocol=tcp&time_range=3600"
サンプル出力:
{
"CustomerID": "0",
"agentID": "1",
"time": "2025-01-15T14:30:45.123Z",
"tcp": {
"anomaly_mad": 15.2,
"drops": 3,
"latency": 45.6,
"anomaly_distribution": 8.9
},
"anomaliesDetected": true,
"summary": "TCP protocol showing elevated anomaly indicators"
}
K) Performance Trends API
直近1時間の平均レイテンシを、過去 N日(デフォルト 7日、前日まで)のベースラインと比較します。
このAPIは、時間の経過に伴うエージェントのパフォーマンストレンドを分析し、現在のパフォーマンスを過去のベースラインと比較して、劣化パターンとパフォーマンスステータスを特定します。
/api/v1/trendsエンドポイントで使用されます。agent_id、customer_id、およびオプションのlookback_daysパラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/trends?agent_id=<agentID>&customer_id=<customerID>&lookback_days=7"
サンプル出力:
{
"CustomerID": "0",
"agentID": "1",
"time": "2025-01-15T14:30:45.123Z",
"currentLatency": 42.5,
"baselineLatency": 35.2,
"trendPercentage": 20.7,
"status": "DEGRADED",
"lookbackDays": 7
}
L) Health Report API
レポート期間の平均レイテンシを集計します:1日(daily)、7日(weekly)、30日(monthly)。
このAPIは、エージェントパフォーマンス分布、ランキング、およびネットワーク最適化のための実用的な推奨事項を含む包括的なネットワークヘルスレポートを生成します。
/api/v1/health-reportエンドポイントで使用されます。customer_id、オプションのreport_period(daily, weekly, monthly)、およびinclude_recommendations(true/false)パラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/health-report?customer_id=<customerID>&report_period=daily&include_recommendations=true"
サンプル出力:
{
"CustomerID": "0",
"reportPeriod": "daily",
"generatedAt": "2025-01-15T14:30:45.123Z",
"summary": {
"totalAgents": 5,
"healthDistribution": {
"good": 3,
"fair": 1,
"poor": 1
},
"overallScore": 76.0
},
"agentDetails": [
{
"agentID": "1",
"avgLatency": 25.3,
"status": "GOOD"
},
{
"agentID": "2",
"avgLatency": 65.8,
"status": "FAIR"
},
{
"agentID": "3",
"avgLatency": 120.4,
"status": "POOR"
}
],
"recommendations": [
"監視対象エージェント総数: 5",
"良好なパフォーマンスのエージェント: 3",
"注意が必要なエージェント: 1",
"即座の調査が必要なエージェント: 1",
"優先事項: POORステータスのエージェントを調査してください"
]
}
M) Agent Rankings API
time_range 秒(デフォルト 24時間)の平均レイテンシでエージェントをランク付けします。
このAPIは、パフォーマンスメトリクスとトレンドによってすべてのエージェントをランク付けし、詳細なパフォーマンススコアと比較分析を使用して上位および下位のパフォーマーを特定します。
/api/v1/agent-rankingsエンドポイントで使用されます。customer_id、オプションのmetric(latency, stability, connectivity_health, overall)、およびtime_range(秒単位)パラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/agent-rankings?customer_id=<customerID>&metric=overall&time_range=86400"
サンプル出力:
{
"CustomerID": "0",
"metric": "overall",
"timeRangeSeconds": 86400,
"generatedAt": "2025-01-15T14:30:45.123Z",
"totalAgents": 5,
"rankings": [
{
"agentID": "1",
"avgLatency": 22.4,
"performanceScore": 77.6,
"rank": 1
},
{
"agentID": "3",
"avgLatency": 45.2,
"performanceScore": 54.8,
"rank": 2
},
{
"agentID": "2",
"avgLatency": 85.7,
"performanceScore": 14.3,
"rank": 3
}
],
"topPerformer": {
"agentID": "1",
"avgLatency": 22.4,
"performanceScore": 77.6,
"rank": 1
},
"bottomPerformer": {
"agentID": "2",
"avgLatency": 85.7,
"performanceScore": 14.3,
"rank": 3
}
}
N) Correlation Analysis API
time_range 秒(デフォルト 2時間)のレイテンシを、5分単位で集計して分析します。
このAPIは、エージェント間の相関パターンを検出して、複数の場所に影響を与えるネットワーク全体の問題を統計的相関分析とパターン分類で特定します。
/api/v1/correlation-analysisエンドポイントで使用されます。customer_id、オプションのcorrelation_threshold(0.0-1.0)、およびtime_range(秒単位)パラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/correlation-analysis?customer_id=<customerID>&correlation_threshold=0.7&time_range=7200"
サンプル出力:
{
"CustomerID": "0",
"time": "2025-01-15T14:30:45.123Z",
"correlationThreshold": 0.7,
"timeRangeSeconds": 7200,
"totalAgentsAnalyzed": 4,
"patternsFound": 2,
"patterns": [
{
"description": "類似のレイテンシ劣化パターンを示すエージェント",
"affectedAgents": ["1", "2", "4"],
"correlationStrength": 0.85,
"patternType": "similar_degradation",
"severity": "MEDIUM",
"recommendation": "共有ネットワークインフラストラクチャを調査 - 複数のエージェントが同様に影響を受けています"
},
{
"description": "逆のレイテンシパターンを示すエージェント",
"affectedAgents": ["3", "5"],
"correlationStrength": 0.72,
"patternType": "inverse_pattern",
"severity": "LOW",
"recommendation": "異なるエージェントに影響を与えるロードバランシングまたはフェイルオーバー動作を確認してください"
}
]
}
O) Degradation Alerts API
直近1時間の平均レイテンシを、days_lookback 日(デフォルト 3日、前日まで)のベースラインと比較します。
このAPIは、設定可能なしきい値を超えるパフォーマンス低下を示すエージェントを、重大度分類と詳細な劣化分析で積極的に識別します。
/api/v1/degradation-alertsエンドポイントで使用されます。customer_id、オプションのseverity_threshold(パーセンテージ)、およびdays_lookbackパラメータを追加できます。
curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/degradation-alerts?customer_id=<customerID>&severity_threshold=20&days_lookback=3"
サンプル出力:
{
"CustomerID": "0",
"time": "2025-01-15T14:30:45.123Z",
"alertCount": 2,
"severityThreshold": 20,
"daysLookback": 3,
"alerts": [
{
"agentID": "3",
"degradationPercent": 45.2,
"currentLatency": 78.5,
"baselineLatency": 54.1,
"severity": "HIGH",
"message": "エージェント3は3日間で45.2%のパフォーマンス劣化を示しています"
},
{
"agentID": "2",
"degradationPercent": 22.8,
"currentLatency": 55.3,
"baselineLatency": 45.0,
"severity": "MEDIUM",
"message": "エージェント2は3日間で22.8%のパフォーマンス劣化を示しています"
}
]
}
P) iPerf Throughput Insight API
直近12時間の iPerf TCP/UDP スループット最新値を返します。
この API は、特定 QoSAgent の iPerf 測定から TCP/UDP スループットを返します。
/api/v1/iperf エンドポイントで使用します。
agent_id と customer_id パラメータを追加できます:
curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/iperf?agent_id=<agentID>&customer_id=<customerID>
出力例:
{
"CustomerID": "0",
"agentID": "1",
"time": "2026-06-15T14:59:46.207Z",
"tcp": {
"downloadThroughputMbps": 380.38,
"uploadThroughputMbps": 246.02
},
"udp": {
"downloadThroughputMbps": 120.5,
"uploadThroughputMbps": 98.3
}
}
API定義
OpenAPI標準に準拠したAPI定義ファイルは、yml形式で利用できます。 ファイルはこちらからダウンロードできます。
wget https://api.latence.ca/software/latencetech_api_definition.yml
トラブルシューティング
customerID is requiredまたはagentID is required
使用する環境によっては、クエリのアナライザー部分を引用符で囲む必要がある場合があります。
curl -H "x-api-key: your_api_key_here" -s -k "https://<analyzer_IP>:12099/api/v1/ci?agent_id=<agentID>&customer_id=<customerID>"