Conceptos básicos de la CLI para Node

Q: ¿jq no está instalado en un contenedor mínimo?

Ejecuta desde un bastión o un pod de depuración con jq. Alternativamente, node -e analiza JSON, pero jq es más rápido para operaciones.

10 ejemplos para curl, jq, ss y seguimiento de registros en servidores Linux que ejecutan APIs de Node.js - 7 básicos y 3 intermedios.

Prerrequisitos

Acceso SSH a un host de VM/contenedor de staging o producción (rol de solo lectura para juniors).
curl, jq y ss instalados (predeterminado en la mayoría de las imágenes de Linux).
Conoce el puerto de tu servicio (3000 por defecto) y la ruta de salud (/health).

Ejemplos básicos

1. Comprobación de salud con curl

curl -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

-s silencioso, -f falla en HTTP 4xx/5xx (salida no cero)
Usar en sondeos de balanceadores de carga y scripts de humo de despliegue
ready debería fallar cuando Postgres/Redis no estén accesibles

# Con temporización para el triaje de latencia
curl -sf -w "time_total=%{time_total}\n" -o /dev/null http://localhost:3000/health

2. POST JSON a una API

curl -sf -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -H "x-request-id: cli-smoke-$(date +%s)" \
  -d '{"customerId":"550e8400-e29b-41d4-a716-446655440000","items":[{"sku":"550e8400-e29b-41d4-a716-446655440001","quantity":1}]}'

Siempre envía x-request-id para la correlación de registros
Pasa a través de jq para una salida legible: | jq .

3. Filtrar registros JSON con jq

# Últimas 100 líneas de error de la salida estándar del contenedor
kubectl logs deploy/orders-api --tail=500 | jq -c 'select(.level=="error")' | tail -20
 
# Rastrear una solicitud
kubectl logs deploy/orders-api --since=10m | jq -c 'select(.requestId=="abc-123")'

Los registros de Pino son un objeto JSON por línea, perfecto para jq
select(.statusCode >= 500) para errores HTTP en eventos request_complete

Relacionado: pino - convenciones de campos de registro

4. Listar puertos de escucha con ss

ss -tlnp | grep node
ss -tlnp 'sport = :3000'

ss reemplaza al obsoleto netstat en Linux moderno
Confirma que Node se vinculó a 0.0.0.0:3000, no solo a 127.0.0.1 en contenedores
Comprueba la acumulación de TIME-WAIT bajo carga: ss -s

5. Seguir el Journal de systemd para el servicio Node

sudo journalctl -u orders-api -f --since "15 min ago"
sudo journalctl -u orders-api -p err --since today

-f sigue los registros en vivo en VMs sin Kubernetes
Combínalo con systemctl status orders-api para bucles de reinicio

6. Seguir los registros del contenedor Docker

docker logs -f --tail 200 orders-api
docker logs orders-api 2>&1 | jq -c 'select(.level=="error")' | tail -10

Las aplicaciones Node registran en stdout - Docker lo captura
No uses docker exec para leer archivos de registro que no existen

7. Comprobación de DNS y Upstream desde el servidor

curl -sf https://api.stripe.com/v1/charges -H "Authorization: Bearer sk_test_xxx" -o /dev/null -w "%{http_code}\n"
getent hosts postgres.internal

Distingue un error de la aplicación de un fallo de red/DNS durante incidentes
Ejecuta desde el mismo espacio de nombres de red que el pod de la aplicación cuando sea posible

Ejemplos intermedios

8. Script de humo en el repositorio

#!/usr/bin/env bash
set -euo pipefail
BASE_URL="${BASE_URL:-http://localhost:3000}"
 
curl -sf "$BASE_URL/health" | jq -e '.status == "ok"'
curl -sf "$BASE_URL/ready" | jq -e '.status == "ok"'
echo "smoke OK"

Confirma en bin/smoke.sh; ejecuta post-despliegue en CI o SSH
set -euo pipefail falla rápidamente en el primer error

Relacionado: Mejores prácticas de la CLI de Linux - higiene de scripts

9. Comparar encabezados de respuesta (Caching, Auth)

curl -sI http://localhost:3000/orders/1 | grep -iE 'cache-control|x-request-id|content-type'

-I solicitud HEAD solo para metadatos
Verifica los encabezados de CDN/caché en las rutas GET

10. Comprobación de carga puntual con bucle curl

for i in $(seq 1 20); do
  curl -sf -o /dev/null -w "%{http_code} %{time_total}\n" http://localhost:3000/health
done

Comprobación manual rápida antes de declarar un incidente resuelto
Para pruebas de carga reales, usa k6 o autocannon, no bucles bash en producción

Preguntas frecuentes

¿jq no está instalado en un contenedor mínimo?

Ejecuta desde un bastión o un pod de depuración con jq. Alternativamente, node -e analiza JSON, pero jq es más rápido para operaciones.

¿curl funciona localmente pero no desde mi portátil a producción?

Es lo esperado: la producción está detrás de una VPN o una red privada. Primero, SSH a un bastión o kubectl port-forward.

Relacionado

Inspección de procesos - top, lsof
Mejores prácticas de la CLI de Linux - resumen portátil
Habilidad de triaje de incidentes - comandos de incidentes

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Prerrequisitos

Acceso SSH a un host de VM/contenedor de staging o producción (rol de solo lectura para juniors).
curl, jq y ss instalados (predeterminado en la mayoría de las imágenes de Linux).
Conoce el puerto de tu servicio (3000 por defecto) y la ruta de salud (/health).

Ejemplos básicos

1. Comprobación de salud con curl

curl -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

-s silencioso, -f falla en HTTP 4xx/5xx (salida no cero)
Usar en sondeos de balanceadores de carga y scripts de humo de despliegue
ready debería fallar cuando Postgres/Redis no estén accesibles

# Con temporización para el triaje de latencia
curl -sf -w "time_total=%{time_total}\n" -o /dev/null http://localhost:3000/health

2. POST JSON a una API

curl -sf -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -H "x-request-id: cli-smoke-$(date +%s)" \
  -d '{"customerId":"550e8400-e29b-41d4-a716-446655440000","items":[{"sku":"550e8400-e29b-41d4-a716-446655440001","quantity":1}]}'

Siempre envía x-request-id para la correlación de registros
Pasa a través de jq para una salida legible: | jq .

3. Filtrar registros JSON con jq

# Últimas 100 líneas de error de la salida estándar del contenedor
kubectl logs deploy/orders-api --tail=500 | jq -c 'select(.level=="error")' | tail -20
 
# Rastrear una solicitud
kubectl logs deploy/orders-api --since=10m | jq -c 'select(.requestId=="abc-123")'

Los registros de Pino son un objeto JSON por línea, perfecto para jq
select(.statusCode >= 500) para errores HTTP en eventos request_complete

Relacionado: pino - convenciones de campos de registro

4. Listar puertos de escucha con ss

ss -tlnp | grep node
ss -tlnp 'sport = :3000'

ss reemplaza al obsoleto netstat en Linux moderno
Confirma que Node se vinculó a 0.0.0.0:3000, no solo a 127.0.0.1 en contenedores
Comprueba la acumulación de TIME-WAIT bajo carga: ss -s

5. Seguir el Journal de systemd para el servicio Node

sudo journalctl -u orders-api -f --since "15 min ago"
sudo journalctl -u orders-api -p err --since today

-f sigue los registros en vivo en VMs sin Kubernetes
Combínalo con systemctl status orders-api para bucles de reinicio

6. Seguir los registros del contenedor Docker

docker logs -f --tail 200 orders-api
docker logs orders-api 2>&1 | jq -c 'select(.level=="error")' | tail -10

Las aplicaciones Node registran en stdout - Docker lo captura
No uses docker exec para leer archivos de registro que no existen

7. Comprobación de DNS y Upstream desde el servidor

curl -sf https://api.stripe.com/v1/charges -H "Authorization: Bearer sk_test_xxx" -o /dev/null -w "%{http_code}\n"
getent hosts postgres.internal

Distingue un error de la aplicación de un fallo de red/DNS durante incidentes
Ejecuta desde el mismo espacio de nombres de red que el pod de la aplicación cuando sea posible

Ejemplos intermedios

8. Script de humo en el repositorio

#!/usr/bin/env bash
set -euo pipefail
BASE_URL="${BASE_URL:-http://localhost:3000}"
 
curl -sf "$BASE_URL/health" | jq -e '.status == "ok"'
curl -sf "$BASE_URL/ready" | jq -e '.status == "ok"'
echo "smoke OK"

Confirma en bin/smoke.sh; ejecuta post-despliegue en CI o SSH
set -euo pipefail falla rápidamente en el primer error

Relacionado: Mejores prácticas de la CLI de Linux - higiene de scripts

9. Comparar encabezados de respuesta (Caching, Auth)

curl -sI http://localhost:3000/orders/1 | grep -iE 'cache-control|x-request-id|content-type'

-I solicitud HEAD solo para metadatos
Verifica los encabezados de CDN/caché en las rutas GET

10. Comprobación de carga puntual con bucle curl

for i in $(seq 1 20); do
  curl -sf -o /dev/null -w "%{http_code} %{time_total}\n" http://localhost:3000/health
done

Comprobación manual rápida antes de declarar un incidente resuelto
Para pruebas de carga reales, usa k6 o autocannon, no bucles bash en producción

Preguntas frecuentes

¿jq no está instalado en un contenedor mínimo?

Ejecuta desde un bastión o un pod de depuración con jq. Alternativamente, node -e analiza JSON, pero jq es más rápido para operaciones.

¿curl funciona localmente pero no desde mi portátil a producción?

Es lo esperado: la producción está detrás de una VPN o una red privada. Primero, SSH a un bastión o kubectl port-forward.

Relacionado

Inspección de procesos - top, lsof
Mejores prácticas de la CLI de Linux - resumen portátil
Habilidad de triaje de incidentes - comandos de incidentes

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Conceptos básicos de la CLI para Node

Buscar en la documentación

Conceptos básicos de la CLI para Node