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:

Destination Resource Purpose
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:

Component Version
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.

AWS Emulator running locally with its HTTPS endpoint and generated configuration paths

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.

The telemetry S3 bucket, DynamoDB table, and SQS queue in AWS Emulator

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.

Recorded response for CPU usage of 92.5 percent, with the alert flag enabled

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 

A HIGH_CPU_USAGE message received from the local high-cpu-alerts queue

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:

Check Result Scope
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

Three passing HTTP E2E tests in Vitest

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.