LocalStack Monitoring with Vigilmon

LocalStack is a cloud emulator that runs AWS services locally — S3, SQS, DynamoDB, Lambda, and over 80 other services — without connecting to AWS. It's widely used in CI pipelines, local development, and integration test suites. When LocalStack is down or a specific emulated service is unavailable, every test that depends on it fails with cryptic connection errors.

This guide covers how to monitor LocalStack environments with Vigilmon.

LocalStack Health Endpoints

LocalStack exposes several health and status endpoints out of the box.

Default port: 4566

# Overall health — all emulated services and their status
GET http://localhost:4566/_localstack/health

# Returns:
{
  "services": {
    "s3": "running",
    "sqs": "running",
    "dynamodb": "running",
    "lambda": "running",
    "cloudwatch": "available",
    ...
  },
  "version": "3.x.x"
}

# Liveness probe
GET http://localhost:4566/_localstack/health?reload

# Info endpoint
GET http://localhost:4566/_localstack/info

Service statuses:

• running — initialized and handling requests
• available — can start on demand but not yet initialized
• error — service failed to start

Monitoring a Shared LocalStack Instance

In many teams, a shared LocalStack instance runs on a development server or in a long-lived CI environment. Monitoring this instance tells you when it's down before developers start debugging phantom test failures.

Monitor 1: LocalStack Overall Health

1. Log in to Vigilmon → Monitors → New Monitor
2. Type: HTTP
3. Method: GET
4. URL: http://localstack.dev.internal:4566/_localstack/health
5. Interval: 1 minute
6. Expected status code: 200
7. Keyword check: "version"
8. Save

Monitor 2: Specific Service Availability

If your team depends on specific services (e.g., S3 for file storage tests), add service-specific monitors using keyword checks:

1. Type: HTTP
2. Method: GET
3. URL: http://localstack.dev.internal:4566/_localstack/health
4. Interval: 1 minute
5. Keyword check: "s3":"running"
6. Save

Repeat for other critical services: "sqs":"running", "dynamodb":"running", "lambda":"running".

Monitor 3: LocalStack Pro Dashboard (if using Pro)

LocalStack Pro includes a dashboard accessible at port 4566:

1. Type: HTTP
2. Method: GET
3. URL: http://localstack.dev.internal:4566/_localstack/diagnose
4. Interval: 5 minutes
5. Expected status code: 200
6. Save

CI Pipeline Monitoring

LocalStack is commonly started as a Docker container in CI pipelines. Monitoring here is about detecting when the startup health check takes too long or fails silently.

Docker Compose health check

Add a health check to your docker-compose.yml so CI systems (and Vigilmon in a local Docker setup) can probe it:

services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    environment:
      - SERVICES=s3,sqs,dynamodb,lambda
      - DEBUG=0

Startup wait script

For CI pipelines, use a wait script to block test runs until LocalStack is ready:

#!/bin/bash
echo "Waiting for LocalStack..."
max_wait=120
waited=0

until curl -sf http://localhost:4566/_localstack/health | grep -q '"s3":"running"'; do
  sleep 2
  waited=$((waited + 2))
  if [ $waited -ge $max_wait ]; then
    echo "LocalStack failed to start in ${max_wait}s"
    exit 1
  fi
done

echo "LocalStack ready after ${waited}s"

If this script times out in CI, your pipeline fails with a clear message instead of cryptic AWS SDK connection errors.

Key Metrics to Watch

| Metric | What it means | Healthy threshold | |--------|--------------|-------------------| | /health status code | LocalStack is responding | 200 always | | Service status in /health | Specific service is available | All required services running | | Startup time | Time from container start to ready | < 30 seconds | | Memory usage | LocalStack emulation overhead | < 2 GB for typical service set | | Lambda cold start time | Lambda function invocation | < 5 seconds |

Monitoring LocalStack in Remote Dev Environments

Some teams run a shared LocalStack on an always-on server for local development. Add these monitors:

TCP Port Monitor

Before HTTP monitoring, verify the port is open:

1. Type: TCP
2. Host: localstack.dev.internal
3. Port: 4566
4. Interval: 1 minute
5. Save

A TCP monitor catches container crashes before the HTTP health endpoint becomes relevant.

SQS Queue Availability

If your application depends on SQS, verify the SQS service is responding:

# List queues via the LocalStack SQS endpoint
curl -s "http://localstack.dev.internal:4566/000000000000/" \
  -d "Action=ListQueues"

Add an HTTP monitor for this URL that checks for a 200 response.

Alerting Recommendations

Critical alerts (notify immediately):

• /health non-200 — LocalStack is down; all integration tests will fail
• Required service not running — tests depending on that service will fail
• TCP port 4566 not accepting connections — container is crashed

Warning alerts:

• Memory usage climbing toward container limit — restart may be needed soon
• Startup time exceeded 60 seconds — likely resource contention on the host

Suggested Vigilmon alert settings:

• Confirmation: 1 failure (dev environments should alert fast — tests fail immediately)
• Recovery: 2 consecutive successes
• Channels: Slack channel for the dev team

LocalStack Pro Extensions

LocalStack Pro adds a /extensions endpoint and more detailed diagnostics:

# Check installed extensions
GET http://localhost:4566/_localstack/extensions

# Detailed diagnostics (memory, threads, etc.)
GET http://localhost:4566/_localstack/diagnose

Both are useful for Vigilmon keyword monitors if your team uses Pro features.

Testing Your Monitors

Verify your monitors by stopping LocalStack and confirming alerts fire:

# Stop LocalStack
docker stop localstack

# Vigilmon should alert within 1–2 minutes

# Restart LocalStack
docker start localstack

# Wait for recovery notification

For service-specific monitors, you can test by starting LocalStack with a reduced service set:

# Start LocalStack without SQS
SERVICES=s3,dynamodb docker-compose up localstack

Your SQS service monitor should alert while S3 and DynamoDB monitors stay green.

Summary

LocalStack monitoring focuses on two signals: the container is running and the specific services your tests depend on are in running state. With Vigilmon monitoring your shared LocalStack instance, developers get alerted immediately when the emulator goes down instead of discovering it through confusing test failures.

Set up your LocalStack monitors at vigilmon.online.