I Tried the New AWS Emulator with NestJS: Local Telemetry with S3, DynamoDB and SQS
DEV Community

I Tried the New AWS Emulator with NestJS: Local Telemetry with S3, DynamoDB and SQS

AWS announced AWS Emulator on November 11, 2026: a local endpoint that lets your AWS CLI and SDK clients talk to emulated AWS APIs. I tried it with a small backend workflow: receive telemetry, store it, and publish an alert when CPU usage is high. Official AWS announcement.

The result is a NestJS + TypeScript telemetry API using the AWS SDK for JavaScript v3, with emulated S3, DynamoDB, and SQS. Source code, setup scripts, tests, and all screenshots: aws-emulator-telemetry-lab on GitHub. The repository includes both an English guide and a Spanish guide.

What the API does

A client submits a measurement to POST /telemetry. After validation, the service performs these operations in order:

  • DynamoDB AgentStatus - Replace the latest status for an agent
  • S3 telemetry-raw-logs - Save a JSON report for each measurement
  • SQS high-cpu-alerts - Send an alert when cpuUsage >= 80

The table uses a string partition key named agentId. S3 objects use logs/<agentId>/<uuid>.json, so history and current state have different storage models.

This repository does not collect system metrics automatically. The examples use curl as the telemetry sender, and there is no SQS consumer yet.

The environment I verified

The lab was verified on November 21, 2026:

  • OS: Linux Mint 22.3, x86_64
  • Node.js / npm: 24.22.1 / 11.19.1
  • AWS CLI: 2.36.29
  • AWS Emulator: 1.0.551
  • TypeScript: 6.0.3
  • Vitest: 4.1.12

These are recorded lab versions, rather than a claim about the latest releases. The environment record contains the details.

1. Start a local emulator

Install Node.js, npm, AWS CLI v2, and AWS Emulator first. For Linux Mint, follow AWS's Debian package installation and signature verification instructions. The repository's guide includes a package URL pinned to the tested emulator build.

In terminal A:

aws-emulator --version
aws-emulator

Keep it running. The lab uses the HTTPS endpoint https://127.0.0.1:9297.

2. Configure a shell for local AWS calls

In terminal B, clone the repository once:

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

Skip cloning if you already have the project. Adjust the directory if you keep your projects elsewhere.

The script points the CLI and SDK at the local endpoint, selects us-east-1, and uses the emulator's generated credentials and certificate under ~/.aws/emulator/9297/. It also unsets inherited AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, and AWS_PROFILE.

Use source in every shell that runs the backend or AWS commands. Running the script as a child process would not retain those exports in your current shell.

Check the connection:

curl --fail --silent --show-error \
  --cacert "$AWS_CA_BUNDLE" \
  https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

The health check should return ok; the emulated account is 000000000000. If you see another account, inspect your configuration before continuing. AWS documents the SDK endpoint and certificate settings.

3. Initialize the resources and start NestJS

From the configured repository shell:

bash scripts/init-aws.sh

The script checks the endpoint and STS account before creating or reusing the named resources. It also waits for AgentStatus to become available and checks its status and key.

Then start the backend from its own directory:

cd backend
npm ci
if [ ! -f .env ] ; then cp .env.example .env fi
npm run start:dev

The local .env contains:

S3_BUCKET_NAME=telemetry-raw-logs
DYNAMODB_TABLE_NAME=AgentStatus
SQS_QUEUE_NAME=high-cpu-alerts

The API listens on http://127.0.0.1:3000. The current code explicitly binds that address and port; it does not read PORT. The API's HTTP listener is separate from the emulator's HTTPS endpoint.

AppService refuses startup unless AWS_ENDPOINT_URL exactly matches https://127.0.0.1:9297.

Two SDK configuration choices matter here:

  • S3 uses forcePathStyle: true.
  • SQS uses useQueueUrlAsEndpoint: false, retaining the configured local transport endpoint even when a returned queue URL looks like an AWS URL.

You can inspect the complete implementation in app.service.ts.

4. Send normal telemetry

In terminal C:

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 }'

The expected response is 201 Created, with status: "processed" and alertTriggered: false. It also includes a generated timestamp and S3 object key.

To inspect the stored result, configure terminal C from the repository root:

cd ~/Proyectos/aws-emulator-telemetry-lab
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/

5. Trigger and inspect a high CPU alert

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 }'

In the recorded manual run, this returned alertTriggered: true. The threshold is 80% inclusive. Memory usage is stored but does not trigger an alert, and repeated high CPU requests produce repeated alerts.

From a shell configured with use-emulator.sh:

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

Receiving a message changes its visibility temporarily; it does not delete it. A visible-message count of zero after receiving does not establish that the message was deleted.

6. Reject invalid input

Both usage fields must be JSON numbers between 0 and 100. agentId and hostname must be nonempty strings, and all four fields are required. The global ValidationPipe also rejects extra fields.

This request should return 400 Bad Request before calling the service:

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 }'

7. Know exactly what your tests prove

From backend/:

npx vitest run --config vitest.config.ts
npx vitest run --config vitest.config.e2e.ts
npm run build

Verified results:

  • Unit tests: 2 passed - Controller delegation and returned result/alert flag
  • HTTP E2E tests: 3 passed - Valid POST, CPU above 100, missing agent ID
  • NestJS build: Passed - TypeScript compilation

Both automated suites mock AppService. They do not test AWS SDK operations or the service's CPU threshold logic against the emulator. They can run without the emulator.

The S3, DynamoDB, and SQS workflow was checked manually and recorded in the screenshots. During the documentation review, the tests and build were rerun successfully, alongside read-only emulator checks. The full manual POST/storage/message workflow was not rerun in that review.

That distinction is the most useful testing lesson from this exercise: a passing HTTP test and a demonstrated service integration answer different questions.

What I would improve next

The current implementation writes sequentially: DynamoDB, then S3, then optional SQS. There is no transaction across them. A failure can leave partial data, and a retry can create additional objects or messages.

The backend also lacks authentication, authorization, rate limiting, idempotency handling, and an alert consumer. Next improvements would include service tests at the 80% boundary, partial-failure tests, a consumer, and an automated emulator integration workflow.

AWS Emulator itself is intended for development and testing. Resources are held in memory and lost when it stops, and its behavior does not establish production compatibility or IAM policy correctness. See the official limitations.

Keep both services on loopback, use emulator credentials, and trust the generated CA. This lab does not require disabling TLS verification. Stop the backend and emulator with Ctrl+C when finished; restart resource initialization and the backend after restarting the emulator.

Try the lab. Explore the GitHub repository, follow either language guide, and compare your results with the captured evidence. If you find a reproducibility problem or want to propose an improvement, open an issue. Which would you add first: an SQS consumer, idempotency handling, or automated integration tests?

Also available in Spanish. For a Spanish walkthrough of this lab, read the article on AWS Builder Center. Both articles link to the same GitHub repository and its verified setup instructions.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.