Integración PHP HTTP
La extensión cURL de PHP puede llamar a Telemetry HTTP API sin un paquete de cliente adicional. Mantenga la clave API en la configuración del lado del servidor y utilice conexiones explícitas y tiempos de espera de solicitud.
Configurar y enviar un evento
<?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 agrega timestamp_utc. No envíe credenciales, encabezados de autorización, cookies, solicitudes de entrada, textos de excepción ni contenido privado del cliente. Utilice una clave con ámbito de escritura para la ingesta.
enviar un lote
El valor data puede ser una serie de filas compatibles:
$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",
],
],
];
Mantenga los lotes delimitados y compatibles con el esquema. Si la aplicación pone en cola eventos, defina la profundidad máxima, la antigüedad máxima, el comportamiento de desbordamiento, el presupuesto de reintento y el manejo de apagado.
Ejecutar una consulta
Utilice una clave de alcance de lectura:
<?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.
}
Utilice el Consulta asincrónica API para exportaciones grandes de JSON o Parquet.
Política de reintentos y fallos
Un tiempo de espera es ambiguo: es posible que el servidor haya aceptado el evento antes de que se perdiera la respuesta. Reintente solo fallas de conexión transitorias, 429, 502, 503 y 504. Reutilice event_id, aplique retroceso con fluctuación y limite los intentos. No vuelva a intentar un 400 sin cambios.
Para los análisis ordinarios, la falla de la telemetría no debe reemplazar la respuesta completa del cliente. Utilice una bandeja de salida duradera propiedad de la aplicación para facturación o eventos de auditoría aprobados que no se pueden descartar.
Verificar y solucionar problemas
Consulta las filas más nuevas e inspecciona el esquema a través de GET /tables/<table>/schema. Ejercite ramas de éxito, fracaso, reintento y tiempo de espera.
- Clave API vacía: valide la configuración del lado del servidor antes de construir la solicitud.
curl_execdevuelvefalse: registrocurl_errnoy una categoría de error controlada, no la clave ni la carga útil.401o403: sustituir la llave o corregir su alcance.400: inspeccionar el nombre de la tabla, la forma de JSON y la compatibilidad de tipos.- Cierre del proceso: las llamadas directas HTTP no tienen cola en segundo plano para vaciar; realice un seguimiento de las solicitudes requeridas o persista los eventos primero.
Consulte Integración de Laravel, Registro API, límites de tasa y guía de procesamiento por lotes.