Cómo habilitar CloudWatch Logs en API Gateway: REST, HTTP y WebSocket

Para habilitar CloudWatch Logs en API Gateway, primero identifica el tipo de API: las API REST y WebSocket admiten logs de ejecución y de acceso; las HTTP API admiten solo logs de acceso. REST y WebSocket necesitan un rol IAM de CloudWatch Logs configurado por cuenta y región. En una HTTP API, crea un grupo de CloudWatch Logs y asígnalo a cada etapa que quieras registrar.

El registro se configura por etapa. Guardar un ajuste de logging de etapa no requiere publicar un deployment nuevo. Los cambios en recursos, métodos, rutas o integraciones sí requieren publicar la configuración de la API en REST y WebSocket; una HTTP API los publica automáticamente solo si su etapa tiene autoDeploy habilitado. Consulta las guías de actualizaciones REST, despliegue WebSocket y etapas HTTP.

Los logs de ejecución describen cómo API Gateway procesa una solicitud o mensaje y ayudan a investigar errores dentro del gateway. Los logs de acceso registran una entrada por solicitud con los campos $context que selecciones, por ejemplo, el identificador de solicitud, la ruta, el estado HTTP y la latencia. Puedes habilitar ambos tipos de manera independiente en REST y WebSocket; en HTTP API, configura el registro de acceso.

Antes de configurar el registro

Elige la cuenta, región, API y etapa que quieres observar. Los logs de acceso se configuran por etapa. La API debe tener una etapa antes de poder recibir invocaciones; para comprobar los logs, también tendrás que generar una solicitud o un mensaje de prueba. AWS documenta cómo desplegar una API REST y cómo ver sus grupos de logs.

Para logs de REST y WebSocket, configura el rol de CloudWatch Logs en API Gateway. En IAM, crea un rol cuyo servicio de confianza sea apigateway.amazonaws.com y asígnale la política administrada AmazonAPIGatewayPushToCloudWatchLogs. En la consola de API Gateway, selecciona la región, abre Settings → Logging y guarda el ARN en CloudWatch log role ARN. Es una configuración de cuenta y región, compartida por las API que la usan; no crees otra por cada etapa. AWS explica el rol, la política y el requisito de AWS STS regional.

Si el rol ya está configurado, conserva el existente. Para establecerlo desde la AWS CLI en us-east-1, reemplaza el ID de cuenta y el nombre del rol:

aws apigateway update-account \
  --patch-operations op='replace',path='/cloudwatchRoleArn',value='arn:aws:iam::123456789012:role/APIGatewayToCloudWatchLogs' \
  --region us-east-1

update-account cambia la configuración de la cuenta en la región indicada; repite el ajuste en cada región donde lo necesites. La identidad que ejecuta el comando necesita permiso apigateway:PATCH para actualizar la cuenta y iam:PassRole para pasar el rol a API Gateway. Si el servicio no puede asumir el rol, confirma la relación de confianza, la política y que AWS STS esté activo allí. Consulta la referencia de AWS CLI para update-account y las acciones IAM de API Gateway.

Las HTTP API usan otro flujo: crea un grupo de CloudWatch Logs y permite que la identidad que guarda la configuración de API Gateway administre la entrega de logs y la etapa. La guía de logging para HTTP API publica la lista de permisos para crear el grupo y configurar la entrega, incluidos logs:CreateLogGroup, logs:CreateLogDelivery, logs:PutResourcePolicy, logs:UpdateLogDelivery y logs:DeleteLogDelivery. La identidad también necesita apigateway:PATCH para actualizar la etapa, según la referencia IAM de API Gateway V2. No configures el rol cloudWatchRoleArn como sustituto de esos permisos.

Habilitar logs de ejecución y acceso

API REST

1. Abre la API REST y elige una etapa existente. En Logs and tracing, selecciona Edit.

2. En CloudWatch Logs, elige ERROR para registrar errores o INFO si necesitas los eventos informativos de ejecución. AWS recomienda uno de esos niveles. Deja Data tracing desactivado en producción: registra detalles de solicitudes y respuestas que pueden contener información sensible. API Gateway oculta algunos valores, como claves de API y encabezados de autorización, pero esa redacción no cubre todos los campos de tu aplicación. Consulta la guía de logs de ejecución para REST.

3. Para registrar accesos, crea o elige un grupo de CloudWatch Logs en la cuenta y región de la API, activa Custom access logging, indica el ARN del grupo y pega un formato JSON de una sola línea. En REST, el formato debe incluir $context.requestId o $context.extendedRequestId; incluir ambos facilita la correlación con otros registros. La guía de logs de acceso REST muestra las variables compatibles. Por ejemplo:

   {"requestId":"$context.requestId","extendedRequestId":"$context.extendedRequestId","method":"$context.httpMethod","resourcePath":"$context.resourcePath","status":"$context.status","latencyMs":"$context.responseLatency"}

4. Guarda los cambios.

En el modo estándar, los eventos de ejecución REST se truncan a 1 KiB y API Gateway administra el nombre del grupo. Si necesitas otro destino o conservar eventos mayores, AWS ofrece CloudWatch Logs delivery para logs de ejecución: admite eventos de hasta 1 MiB, pero reemplaza el flujo estándar para esa etapa.

API WebSocket

1. Abre la API WebSocket y elige la etapa. En Logs and tracing, activa el nivel de ejecución ERROR o INFO para las rutas que quieras observar. Puedes configurar el valor predeterminado de las rutas y sobrescribirlo por ruta.

2. Si necesitas registrar el payload completo de mensajes, Data tracing puede hacerlo; evita activarlo en producción porque los mensajes pueden incluir datos personales o secretos.

3. Para logs de acceso, elige un grupo de CloudWatch Logs y usa variables propias de WebSocket. eventType toma los valores CONNECT, MESSAGE o DISCONNECT; routeKey identifica la ruta y connectionId identifica la conexión. Un formato JSON compacto podría ser:

   {"requestId":"$context.requestId","eventType":"$context.eventType","routeKey":"$context.routeKey","connectionId":"$context.connectionId","status":"$context.status"}

   El formato debe ocupar una sola línea e incluir $context.requestId. No uses httpMethod o resourcePath como si fueran mensajes HTTP. Consulta la lista completa de variables en la guía de logging para WebSocket.

API Gateway crea el grupo de ejecución WebSocket /aws/apigateway/{api-id}/{stage}. La guía de AWS para activar logs de REST y WebSocket explica también la configuración regional del rol y cómo encontrar el grupo administrado.

HTTP API

Una HTTP API no tiene logs de ejecución de API Gateway. Configura logs de acceso así:

1. En CloudWatch, crea un grupo como /apigateway/orders/access en la región de la API y copia su ARN.
2. En API Gateway, abre la HTTP API y ve a Monitor → Logging. Selecciona la etapa, activa Access logging, pega el ARN y elige el formato.
3. Guarda. Usa variables de HTTP API como routeKey, httpMethod, status y responseLatency; revisa la referencia de formatos y variables para HTTP API.

La AWS CLI puede crear el grupo y asignar el formato a una etapa. Cambia el API ID, cuenta y región por los de tu entorno; crea el grupo solo si aún no existe:

aws logs create-log-group \
  --log-group-name '/apigateway/orders/access' \
  --region us-east-1

aws apigatewayv2 update-stage \
  --api-id a1b2c3d4 \
  --stage-name '$default' \
  --access-log-settings '{"DestinationArn":"arn:aws:logs:us-east-1:123456789012:log-group:/apigateway/orders/access","Format":"{\"requestId\":\"$context.requestId\",\"time\":\"$context.requestTime\",\"method\":\"$context.httpMethod\",\"routeKey\":\"$context.routeKey\",\"status\":\"$context.status\",\"latencyMs\":\"$context.responseLatency\"}"}' \
  --region us-east-1

El ARN sigue la forma arn:aws:logs:{region}:{account-id}:log-group:{log-group-name}. En este ejemplo, las comillas simples protegen $default y las variables $context de la shell. La referencia de AWS CLI para update-stage muestra la estructura de access-log-settings.

Comprobar los logs y encontrar errores

Envía una solicitud segura a una ruta que ya exista. Por ejemplo, para una etapa con nombre en REST o HTTP API:

GATEWAY_API_ID=a1b2c3d4
GATEWAY_REGION=us-east-1
GATEWAY_STAGE=dev
GATEWAY_ROUTE=health

curl -i "https://${GATEWAY_API_ID}.execute-api.${GATEWAY_REGION}.amazonaws.com/${GATEWAY_STAGE}/${GATEWAY_ROUTE}"

Reemplaza los valores y agrega la autenticación requerida por tu API. Una etapa HTTP API $default se invoca sin el segmento de etapa en la URL. Para WebSocket, usa un cliente compatible para conectarte y enviar un mensaje. Toda solicitud real puede invocar tu backend y generar cargos; prueba una ruta que no modifique datos y una etapa controlada.

En CloudWatch, cambia a la misma región de la API y abre Logs → Log groups. Busca el grupo de ejecución o el grupo de acceso que configuraste, luego el flujo más reciente. La entrega puede tardar un poco. Si tienes más de un grupo, revisa también su nombre y la etapa asociada.

Con JSON estructurado puedes filtrar errores de servidor en CloudWatch Logs Insights. Esta consulta usa los nombres del formato HTTP API de arriba:

fields @timestamp, requestId, method, routeKey, status, latencyMs
| filter status like /^5[0-9][0-9]$/
| sort @timestamp desc
| limit 20

En el formato JSON, status llega como texto; la expresión regular selecciona códigos 5xx sin convertirlo a número. Puedes ver solicitudes recientes desde el lenguaje de consultas de CloudWatch Logs Insights.

Los logs ayudan a inspeccionar solicitudes concretas; las métricas ayudan a ver tasas y tendencias. Para REST, revisa Count, 4XXError, 5XXError, Latency e IntegrationLatency; para HTTP API, los nombres son Count, 4xx, 5xx, Latency e IntegrationLatency. WebSocket expone métricas propias como ConnectCount, MessageCount, ClientError, ExecutionError e IntegrationError. Activar métricas detalladas por método, recurso o ruta puede tener cargos adicionales. Consulta las referencias de métricas REST, métricas HTTP API y métricas WebSocket.

Si API Gateway integra una Lambda, sus eventos aparecen en el grupo /aws/lambda/{nombre-de-la-función}. Ese grupo registra el proceso de Lambda; los logs de API Gateway registran el procesamiento del gateway. Para entender CloudWatch como conjunto de métricas, logs y trazas, mira CloudWatch explicado fácil. El video ¿Dónde están mis logs en AWS? se enfoca en encontrar logs en una aplicación serverless. Para estructurar logs de aplicación y emitir métricas propias desde Lambda, consulta logs estructurados y métricas personalizadas con CloudWatch. Los tres videos son del canal de Marcia en YouTube.

Errores frecuentes

Los logs y las métricas no cubren todos los fallos de entrada. AWS indica que REST o HTTP API pueden no generar telemetría, por ejemplo, para solicitudes 413, 431 (REST), demasiados 429, errores 400 de dominios personalizados sin mapeo y ciertos 500 internos. Revisa los límites de la medición en las guías de monitoreo REST y monitoreo HTTP API.

Seguridad, retención y costos

Los logs de ejecución pueden incluir valores de parámetros, datos del autorizador y, si activas data tracing, el contenido completo de solicitudes y respuestas. Conserva solo los campos que realmente necesitas. Evita tokens, datos personales, claves, cookies y cuerpos de mensajes en los logs de acceso; limita quién puede leer los grupos.

CloudWatch Logs conserva los eventos indefinidamente por defecto. Define una retención compatible con tus requisitos operativos, legales y de auditoría. Por ejemplo, para dejar 30 días en un grupo propio:

aws logs put-retention-policy \
  --log-group-name '/apigateway/orders/access' \
  --retention-in-days 30 \
  --region us-east-1

Treinta días es solo un ejemplo: elige el plazo que corresponda a tu entorno. El costo depende de la región y del volumen que ingieres, conservas y consultas con Logs Insights. Las métricas detalladas también pueden sumar cargos. Revisa la página de precios de CloudWatch y no asumas que el registro será gratuito por habilitarlo.

No borres manualmente los grupos de ejecución que administra API Gateway: AWS advierte que eliminarlos puede interrumpir el registro. Puedes ajustar su retención. El grupo de acceso que creaste tú puede retirarse cuando hayas desactivado el registro de esa etapa y ya no necesites sus datos.

Recursos y comunidad

Para entender cómo se complementan métricas, logs y trazas, lee Observabilidad en la nube de AWS: CloudWatch, X-Ray y CloudTrail, una explicación en español publicada por AWS Community Builders. Si tus logs ya contienen estado y latencia y quieres investigar cómo convertir esos campos en indicadores de servicio, el artículo comunitario Observabilidad desde los logs: cómo construir SLIs sin esperar a instrumentar el código compara metric filters, Embedded Metric Format y consultas de Logs Insights. Para seguir una solicitud entre servicios, continúa con Mejores prácticas de observabilidad en AWS y Observabilidad en AWS con Amazon X-Ray. Si los logs ya te permiten diagnosticar fallos y quieres convertir la salud del servicio en objetivos medibles de disponibilidad y latencia, sigue con Cómo crear SLOs en AWS con CloudWatch Application Signals.

Si buscas un grupo en tu país, explora el directorio de comunidades AWS en Latinoamérica, filtrable por país, tipo de grupo y temas; para encuentros remotos o presenciales, consulta la agenda de eventos AWS y confirma cupos y condiciones en la página de cada actividad. Si estás en Córdoba, puedes conocer al AWS User Group Córdoba y consultar sus actividades en Meetup. Para estudiantes de la región, el AWS Student Community Day Córdoba 2026 está anunciado para el 7 de noviembre de 2026, de 13:00 a 20:00 ART, en FaMAF, Ciudad Universitaria. Al 6 de octubre de 2026, Meetup indicaba registro abierto, entrada gratuita y cupos limitados; revisa la página antes de inscribirte porque la disponibilidad y las condiciones pueden cambiar.