
Probé el nuevo AWS Emulator con NestJS: telemetría local con S3, DynamoDB y SQS
Una experiencia práctica con el nuevo AWS Emulator: una API NestJS en Linux Mint que guarda telemetría en DynamoDB y S3 y genera alertas de CPU en SQS. Incluye pruebas, capturas y el repositorio en GitHub para reproducir el laboratorio.
Una medición, tres destinos
AWS anunció el nuevo AWS Emulator el 11 de noviembre de 2026. Este laboratorio explora su uso con NestJS y tres servicios emulados; puedes consultar el anuncio oficial de AWS .
Una medición de CPU puede servir para consultar el estado actual de un equipo, conservar un historial o generar una alerta. Este laboratorio reúne esos tres comportamientos en una API construida con NestJS y AWS SDK para JavaScript v3.
El flujo comienza con una solicitud a
POST /telemetry . El backend valida los datos, actualiza el estado del agente en DynamoDB, guarda un reporte JSON en S3 y, cuando el uso de CPU alcanza el 80 % o más, envía un mensaje a SQS.Las llamadas del SDK apuntan a AWS Emulator, ejecutándose localmente. AWS describe esta herramienta como una forma de probar aplicaciones contra APIs emuladas sin utilizar una cuenta AWS. Documentación de AWS Emulator .
El código completo de este laboratorio, los scripts de configuración, las pruebas y las capturas están disponibles en mi repositorio de GitHub . También encontrarás una guía paso a paso en español para reproducirlo.
Arquitectura del laboratorio
La API recibe cuatro campos:
agentId , hostname , cpuUsage y memoryUsage .Después de validarlos, realiza estas operaciones en orden:
Servicio emulado | Recurso | Propósito |
|---|---|---|
DynamoDB | AgentStatus | Conservar el último estado de cada agente |
S3 | telemetry-raw-logs | Guardar un reporte JSON por medición |
SQS | high-cpu-alerts | Recibir alertas cuando cpuUsage >= 80 |
DynamoDB utiliza
agentId como clave de partición. Una nueva medición del mismo agente reemplaza su estado anterior. S3 conserva cada reporte con una clave diferente:logs/<agentId>/<uuid>.jsonLa memoria se almacena junto con la CPU, pero no activa alertas. El proyecto tampoco incluye un agente que recolecte métricas automáticamente: para este ejercicio, las solicitudes se envían con
curl .Entorno utilizado
El laboratorio se verificó el 21 de noviembre de 2026 con estas versiones:
Herramienta | Versión |
|---|---|
Sistema operativo | Linux Mint 22.3, x86_64 |
Node.js | 24.22.1 |
npm | 11.19.1 |
AWS CLI | 2.36.29 |
AWS Emulator | 1.0.551 |
TypeScript | 6.0.3 |
Vitest | 4.1.12 |
Son las versiones registradas en este ejercicio. El detalle está en el archivo de evidencias del entorno .
1. Preparar el emulador
Se necesita Node.js, npm y AWS CLI v2 instalados. En Linux Mint se puede utilizar el paquete Debian del emulador; AWS publica las instrucciones de instalación y verificación de firma .
Con el emulador instalado, comprueba la versión:
aws-emulator --versionDespués, inícialo en una terminal:
aws-emulatorEn este laboratorio se utiliza el endpoint:
https://127.0.0.1:9297Mantén esa terminal abierta.

El emulador genera sus propias credenciales y certificado. Los clientes deben utilizar esos archivos para conectarse a la instancia correspondiente. La guía de configuración de SDK explica este mecanismo.
2. Clonar y configurar el proyecto
En otra terminal:
mkdir -p ~/Proyectos
git clone https://github.com/mickychog/aws-emulator-telemetry-lab.git \ ~/Proyectos/aws-emulator-telemetry-lab
cd ~/Proyectos/aws-emulator-telemetry-lab
source scripts/use-emulator.shSi ya tienes el repositorio, omite la clonación.
El script
use-emulator.sh configura el endpoint, la región us-east-1 , los archivos de credenciales y la confianza en el certificado local. También elimina de esa terminal las variables habituales que podrían contener credenciales AWS heredadas.Hay un detalle importante: se carga con
source para conservar sus variables en la terminal actual. Debes repetirlo en cada terminal que ejecute AWS CLI o el backend.Comprueba la conexión:
curl --fail --silent --show-error \ --cacert "$AWS_CA_BUNDLE" \ https://127.0.0.1:9297/__admin/health
aws sts get-caller-identityLa comprobación de salud debe devolver
ok . En este laboratorio, la cuenta emulada es:000000000000Si aparece una cuenta diferente, revisa la configuración antes de continuar.
3. Inicializar S3, DynamoDB y SQS
Desde la raíz del repositorio:
bash scripts/init-aws.shEl script comprueba el endpoint y la cuenta local antes de preparar los recursos:
- Bucket S3
telemetry-raw-logs.
- Tabla DynamoDB
AgentStatus, con claveagentId.
- Cola SQS
high-cpu-alerts.
También espera a que la tabla esté disponible y comprueba su estado y clave.

4. Iniciar la API NestJS
En la terminal configurada:
cd ~/Proyectos/aws-emulator-telemetry-lab/backend
npm ci
if [ ! -f .env ]; then cp .env.example .envfi
npm run start:devEl archivo
.env contiene los nombres de los recursos:S3_BUCKET_NAME=telemetry-raw-logsDYNAMODB_TABLE_NAME=AgentStatusSQS_QUEUE_NAME=high-cpu-alertsLa API escucha en:
http://127.0.0.1:3000Conviene distinguir ambas conexiones: la API local recibe HTTP en el puerto 3000 y el SDK se comunica con el emulador mediante HTTPS en el puerto 9297.
El servicio comprueba que
AWS_ENDPOINT_URL coincida exactamente con el endpoint local esperado. Además, configura S3 con forcePathStyle: true y SQS con useQueueUrlAsEndpoint: false .5. Enviar una medición normal
Desde otra terminal:
curl -i -sS -X POST http://127.0.0.1:3000/telemetry \ -H 'Content-Type: application/json' \ -d '{ "agentId": "node-01", "hostname": "linux-mint-lab", "cpuUsage": 35.5, "memoryUsage": 48.2 }'La respuesta esperada es HTTP 201 Created, con
status: "processed" y alertTriggered: false .También devuelve un timestamp y la clave del objeto creado en S3. Ambos valores se generan durante el procesamiento.
Para consultar el almacenamiento, configura una terminal desde la raíz del repositorio:
source scripts/use-emulator.sh
aws dynamodb get-item \ --table-name AgentStatus \ --key '{"agentId":{"S":"node-01"}}'
aws s3 ls s3://telemetry-raw-logs/logs/node-01/Así se comprueban por separado el estado actual del agente y la existencia de su reporte histórico.
6. Activar una alerta de CPU
Ahora envía una medición por encima del umbral:
curl -i -sS -X POST http://127.0.0.1:3000/telemetry \ -H 'Content-Type: application/json' \ -d '{ "agentId": "node-02", "hostname": "server-test", "cpuUsage": 92.5, "memoryUsage": 76.3 }'En la ejecución registrada, la respuesta indicó
alertTriggered: true .
El servicio guarda la medición y envía a SQS un mensaje con estos campos:
type: HIGH_CPU_USAGEagentIdcpuUsagetimestampPara recibir mensajes desde una terminal configurada:
QUEUE_URL=$(aws sqs get-queue-url \ --queue-name high-cpu-alerts \ --query QueueUrl \ --output text)
aws sqs receive-message \ --endpoint-url "$AWS_ENDPOINT_URL" \ --queue-url "$QUEUE_URL" \ --max-number-of-messages 10 \ --wait-time-seconds 2
Recibir un mensaje cambia temporalmente su visibilidad; no lo elimina. Por eso, un contador de mensajes visibles en cero después de una recepción no demuestra que el mensaje haya sido borrado.

Este proyecto genera alertas, pero todavía no implementa un consumidor que las procese y confirme.
7. Rechazar datos inválidos
El DTO exige los cuatro campos. CPU y memoria deben ser números entre 0 y 100; los identificadores y nombres deben ser strings no vacíos.
Por ejemplo:
curl -i -sS -X POST http://127.0.0.1:3000/telemetry \ -H 'Content-Type: application/json' \ -d '{ "agentId": "node-03", "hostname": "invalid-test", "cpuUsage": 150, "memoryUsage": 40 }'Esta solicitud devuelve 400 Bad Request antes de ejecutar el servicio.
El
ValidationPipe global también rechaza propiedades adicionales, lo que mantiene definido el contrato de entrada de la API.8. Separar las pruebas automatizadas de la integración manual
Desde
backend/ :npx vitest run --config vitest.config.ts
npx vitest run --config vitest.config.e2e.ts
npm run buildLos resultados verificados fueron:
Comprobación | Resultado |
|---|---|
Pruebas unitarias | 2 aprobadas |
Pruebas HTTP E2E | 3 aprobadas |
Compilación NestJS | Correcta |

Las unitarias comprueban la delegación del controlador y la respuesta del servicio simulado. Las E2E comprueban el comportamiento HTTP y la validación, sustituyendo también
AppService por una simulación.Por tanto, esas cinco pruebas no verifican las operaciones del SDK contra el emulador ni la lógica interna que decide el umbral de CPU.
La integración con S3, DynamoDB y SQS se comprobó manualmente y quedó registrada en las capturas. Durante la revisión documental se repitieron las pruebas y la compilación, además de consultas de solo lectura al emulador; no se volvió a ejecutar el flujo manual completo.
Límites y mejoras pendientes
El laboratorio permite estudiar el flujo entre una API y tres servicios emulados, pero tiene límites concretos.
Las escrituras son secuenciales y no forman una transacción. Si DynamoDB se actualiza y la escritura en S3 falla, puede quedar un estado parcial. Reintentar una solicitud también puede generar objetos o alertas adicionales.
El backend aún no incluye autenticación, autorización, límites de solicitudes ni claves de idempotencia.
Por su parte, AWS Emulator mantiene los recursos en memoria y los pierde al detenerse. Su comportamiento tampoco permite acreditar la seguridad de políticas IAM ni la compatibilidad completa con producción. AWS detalla estas restricciones en sus limitaciones oficiales .
Para reproducir el ejercicio, conserva las conexiones en loopback, utiliza las credenciales del emulador y confía en su certificado. No hace falta desactivar la validación TLS.
Como siguientes mejoras, plantearía pruebas del servicio para el límite del 80 %, simulación de fallos parciales, un consumidor SQS y un flujo automatizado de integración con el emulador.
Código y guía completa
El repositorio incluye el backend, los scripts de configuración, las pruebas y las 14 capturas originales:
El aprendizaje principal fue conectar cada resultado con su evidencia: una respuesta HTTP, un ítem en DynamoDB, un objeto en S3 o un mensaje en SQS. Esa separación también ayuda a explicar con precisión qué parte del sistema comprueba cada prueba.
También disponible en inglés
Puedes leer una adaptación de este laboratorio en inglés en DEV Community . Ambas publicaciones enlazan al mismo repositorio de GitHub, con el código, los scripts y las evidencias verificadas.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article