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 值可能是兼容行的数组：
$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，没有后台队列需要flush；首先跟踪所需的请求或持久化事件。
请参阅 Laravel 集成、日志API、速率限制 和 配料指南。