本文へ移動
Telemetry
ドキュメントを見る
SDK更新日: 2026年7月29日Telemetry 編集チームと製品チームによるレビュー3 最小読み取り時間

コーディング エージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディング エージェント用の集中プロンプト パックを開き、それをここで説明するワークフローに適応させます。

このページの内容
  1. イベントを設定して送信する
  2. バッチを送信する
  3. クエリを実行する
  4. 再試行および失敗ポリシー
  5. 確認とトラブルシューティングを行う

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, レート制限、そして バッチガイド.

関連製品の機能

安定したイベント名、型指定されたフィールド、プライバシーがレビューされたコンテキストをキャプチャします。

所有権と技術リファレンス

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

編集基準を見直す