AWS Builder Center
Probé el nuevo AWS Emulator con NestJS: telemetría local con S3, DynamoDB y SQS

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>.json
La 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 --version
Después, inícialo en una terminal:
aws-emulator
En este laboratorio se utiliza el endpoint:
https://127.0.0.1:9297
Mantén esa terminal abierta.

Terminal mostrando AWS Emulator 1.0.551, fecha de publicación 2026.11.21 y commit de la compilación.

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.sh
Si 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-identity
La comprobación de salud debe devolver  ok . En este laboratorio, la cuenta emulada es:
000000000000
Si 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.sh
El script comprueba el endpoint y la cuenta local antes de preparar los recursos:
  • Bucket S3  telemetry-raw-logs .
  • Tabla DynamoDB  AgentStatus , con clave  agentId .
  • Cola SQS  high-cpu-alerts .
También espera a que la tabla esté disponible y comprueba su estado y clave.

Bucket telemetry-raw-logs, tabla AgentStatus y cola high-cpu-alerts disponibles en AWS Emulator.


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 .env
fi

npm run start:dev
El archivo  .env  contiene los nombres de los recursos:
S3_BUCKET_NAME=telemetry-raw-logs
DYNAMODB_TABLE_NAME=AgentStatus
SQS_QUEUE_NAME=high-cpu-alerts
La API escucha en:
http://127.0.0.1:3000
Conviene 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 .
Estas opciones están implementadas en el  servicio de telemetría .

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 .
Respuesta de la API para CPU al 92,5 %, con alertTriggered igual a true.

El servicio guarda la medición y envía a SQS un mensaje con estos campos:
type: HIGH_CPU_USAGE
agentId
cpuUsage
timestamp
Para 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.

Alerta HIGH_CPU_USAGE de node-02 con CPU al 92,5 % recibida desde high-cpu-alerts.

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 build
Los resultados verificados fueron:
Comprobación
Resultado
Pruebas unitarias
2 aprobadas
Pruebas HTTP E2E
3 aprobadas
Compilación NestJS
Correcta
Dos pruebas unitarias de telemetría aprobadas en Vitest, con el servicio simulado.

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.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article