Medir el tiempo de respuesta de una API con curl

La forma más rápida de ver cuánto tarda una llamada a una API es curl -s -o /dev/null -w '%{time_total}\n' https://api.example.com/, que imprime solo el tiempo total y nada más. Ese número por sí solo no dice si el retraso está en el DNS, la red, el TLS o el propio servidor — para eso hay que dividir la petición en etapas. Aquí van cinco números en vez de uno, y qué hacer con cada uno.

1. ¿Cuánto tardó realmente la petición?

$ clai cuantos segundos tarda en responder esta dirección→ curl -s -o /dev/null -w '%{time_total}\n' https://cliai.tech/1.244094

-o /dev/null descarta el cuerpo de la respuesta, -s oculta la barra de progreso, y -w imprime solo lo que pediste. Ya hay un número, pero no explica nada.

2. Desglosar el tiempo por etapa

$ clai desglosa el tiempo de respuesta por etapa: dns, conexion, tls, primer byte→ curl -s -o /dev/null -w 'dns: %{time_namelookup}\nconnect: %{time_connect}\ntls: %{time_appconnect}\nttfb: %{time_starttransfer}\ntotal: %{time_total}\n' https://cliai.tech/dns: 0.000782connect: 0.299098tls: 0.414729ttfb: 1.124750total: 1.244094

Los valores son acumulativos, no independientes — lo que importa son las diferencias entre ellos. El DNS tardó 0,0008s, establecer la conexión TCP tardó 0,298s, el saludo TLS tardó 0,116s, y desde que TLS está listo hasta el primer byte pasaron 0,71s — eso es el servidor pensando. Ahí está el problema, si lo hay.

3. Leer las diferencias, no los números absolutos

time_namelookup por encima de 0,1s señala al resolutor o a una caché fría. connect - namelookup es la latencia de red hasta el servidor, aproximadamente la mitad del ping de ida y vuelta. starttransfer - appconnect es cuánto tiempo pensó el servidor la petición. total - starttransfer es el tiempo de transferencia del cuerpo, y depende del tamaño de la respuesta.

4. ¿Fue siquiera un 200?

$ clai muestra el tiempo, el codigo de estado y el tamano del cuerpo→ curl -s -o /dev/null -w 'code: %{http_code}  size: %{size_download}  total: %{time_total}\n' https://cliai.tech/code: 200

Un tiempo sin el código de estado no sirve de nada — un 500 rápido no significa que todo esté bien. La lista completa de variables está en man curl, en la sección WRITE-OUT VARIABLES.

5. Una sola medición no basta

$ clai mide el tiempo de respuesta cinco veces seguidas→ for i in $(seq 5); do curl -s -o /dev/null -w '%{time_total}\n' https://cliai.tech/; done

Una sola medición no significa nada. La primera petición casi siempre es más lenta por el DNS frío y el establecimiento de la conexión. Fíjate en la dispersión entre repeticiones, no en el primer número.

6. Llevar el formato a un archivo

$ clai guarda el formato de medicion en un archivo y reutilizalo→ curl -s -o /dev/null -w @curl-format.txt https://cliai.tech/

-w @archivo lee el formato desde un archivo, así la línea larga deja de estorbar. Ese archivo suele guardarse en el repositorio junto a los demás scripts de verificación.

Trampas

• Los valores son acumulativos. time_appconnect ya incluye el DNS y la conexión. Resta la etapa anterior, o concluirás que el TLS tardó medio segundo cuando en realidad es la suma de todo lo previo.
• time_appconnect es cero en HTTP plano. Sin TLS no existe esa etapa, y el cero aquí no es un error de medición.
• curl mide una sola petición, no el rendimiento. Para carga, usa hey, wrk o k6. curl responde a "dónde se va el tiempo", no a "cuánto tráfico aguanta".

Preguntas relacionadas

¿Qué es el TTFB? El tiempo hasta el primer byte — el valor time_starttransfer en la salida. Suele ser la señal más clara de la velocidad del backend.

¿Por qué la primera petición siempre es más lenta? Caché DNS fría, establecimiento de la conexión TCP y el saludo TLS. Una petición repetida por keep-alive se salta las tres.

¿Cómo mido solo el DNS? %{time_namelookup} por sí solo, o dig +stats, que muestra el tiempo de resolución por separado del resto.

Ver también

• Triaje de red en lenguaje llano
• JSON en la línea de comandos
• Comprobar si un puerto está abierto en un servidor remoto

Deja de memorizar los formatos -w de curl — describe qué quieres medir y CliAI escribe el comando. Instálalo en una línea.