PHP HTTP 統合
PHP の cURL 拡張機能は、追加のクライアント パッケージなしで Telemetry HTTP API を呼び出すことができます。 API キーをサーバー側構成に保持し、明示的な接続とリクエストのタイムアウトを使用します。
イベントを設定して送信する
<?php
$apiKey = getenv("TELEMETRY_API_KEY");
if (!is_string($apiKey) || $apiKey === "") {
throw new RuntimeException("TELEMETRY_API_KEY is not configured");
}
$payload = [
"table" => "api_request_completed",
"data" => [
"event_id" => "evt_request_101",
"route_template" => "/api/projects/:id",
"method" => "GET",
"status_code" => 200,
"status" => "success",
"latency_ms" => 184,
],
];
$request = curl_init("https://api.telemetry.sh/log");
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => 2_000,
CURLOPT_TIMEOUT_MS => 10_000,
CURLOPT_HTTPHEADER => [
"Authorization: " . $apiKey,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$curlError = curl_error($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException(
"Telemetry log failed with HTTP " . $status .
($curlError !== "" ? " and a transport error" : "")
);
}
$response = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
Telemetry が追加 timestamp_utc。認証情報、認証ヘッダー、Cookie、入力要求、例外テキスト、または顧客のプライベート コンテンツを送信しないでください。取り込みには書き込みスコープのキーを使用します。
バッチを送信する
の data value は互換性のある行の配列である場合があります。
$payload = [
"table" => "job_completed",
"data" => [
[
"event_id" => "evt_job_101",
"job_name" => "invoice_sync",
"status" => "success",
"duration_ms" => 912,
],
[
"event_id" => "evt_job_102",
"job_name" => "invoice_sync",
"status" => "failed",
"duration_ms" => 2401,
"error_type" => "provider_timeout",
],
],
];
バッチを制限し、スキーマ互換性を維持します。アプリケーションがイベントをキューに入れる場合は、最大深さ、最大経過時間、オーバーフロー動作、再試行バジェット、およびシャットダウン処理を定義します。
クエリを実行する
読み取りスコープのキーを使用します。
<?php
$sql = <<<'SQL'
SELECT
route_template,
COUNT(*) AS requests,
ROUND(AVG(latency_ms), 0) AS avg_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
ORDER BY requests DESC;
SQL;
$request = curl_init("https://api.telemetry.sh/query");
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => 2_000,
CURLOPT_TIMEOUT_MS => 30_000,
CURLOPT_HTTPHEADER => [
"Authorization: " . $apiKey,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["query" => $sql], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException("Telemetry query failed with HTTP " . $status);
}
$results = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
foreach ($results["data"] ?? [] as $row) {
// Validate expected keys and nulls before using the row.
}
を使用します。 非同期クエリ API 大規模な JSON または Parquet エクスポートの場合。
再試行および失敗ポリシー
タイムアウトは曖昧です。サーバーは応答が失われる前にイベントを受け入れた可能性があります。一時的な接続失敗のみを再試行します。 429, 502, 503、そして 504。再利用 event_id、ジッターを使用してバックオフを適用し、試行を制限します。変更されていないものを再試行しないでください 400.
通常の分析では、テレメトリの失敗が顧客の完了した応答に取って代わられるべきではありません。削除できない請求イベントまたは承認された監査イベントには、アプリケーションが所有する耐久性のある送信ボックスを使用します。
確認とトラブルシューティングを行う
最新の行をクエリし、スキーマを検査します。 GET /tables/<table>/schema。成功、失敗、再試行、およびタイムアウトのブランチを実行します。
- 空の API キー: リクエストを作成する前にサーバー側の構成を検証します。
curl_exec返品false: 記録curl_errnoキーやペイロードではなく、制御されたエラー カテゴリ。401または403: キーを置き換えるか、そのスコープを修正してください。400: テーブルの命名、JSON の形状、タイプの互換性を検査します。- プロセスのシャットダウン: 直接の HTTP 呼び出しにはフラッシュするバックグラウンド キューがありません。必要なリクエストを追跡するか、最初にイベントを永続化します。
を参照してください。 Laravelの統合, ログ API, レート制限、そして バッチガイド.