cwproxy

Normal Mode

Proxy a running app

Use normal mode when your application is already listening. cwproxy connects to APP_HOST:APP_PORT and begins accepting traffic on PROXY_PORT. It does not manage the upstream process lifecycle.

export APP_HOST=127.0.0.1
export APP_PORT=8080
export PROXY_PORT=8081
export APP_NAME=my-app
./cwproxy

Inspector Mode

Start and watch the target

Pass the target command after the binary name. cwproxy starts the process, then polls its full process subtree every 100 ms for open TCP LISTEN sockets. The lowest port found is used unless APP_PORT is set explicitly.

# auto-detect port
./cwproxy node ./server.js

# explicit port override
APP_PORT=3000 ./cwproxy python app.py

• Child inherits the full cwproxy environment and stdio.
• SIGTERM and SIGINT are forwarded to the child process.
• cwproxy exits with the child's exit code.
• Wrapper processes and short-lived launchers are supported — the port scanner walks the whole process tree.

CloudWatch Logs

Async delivery with back-pressure

Log events are enqueued to an in-memory channel and flushed to CloudWatch by a background goroutine. The proxy path never blocks on AWS API calls.

• Bounded queue of 1024 events. When full, excess events are dropped and counted; a warning is reported every 100 drops.
• Batches of up to 1000 events or 900 KiB per PutLogEvents call.
• Background flush every 2 seconds and on shutdown.
• Each PutLogEvents call is bounded to a 2-second timeout and retried up to 3× with 100 ms / 200 ms backoff on ThrottlingException and ServiceUnavailableException.
• Shutdown flushes the remaining queue within a 10-second budget before exit.
• Log stream name includes app name, PID, and Unix timestamp — unique across restarts.
• Log group and stream created at startup; ResourceAlreadyExistsException is silently accepted.

EMF Metrics

Metrics embedded in log events

CloudWatch Embedded Metric Format (EMF) data is attached to every log event. CloudWatch extracts it as custom metrics automatically — no cloudwatch:PutMetricData permission needed. Metrics are also emitted to stdout for local consumption.

Required IAM permissions

logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents

Health Checks

Periodic probing with full telemetry

cwproxy runs concurrent HTTP GET probes against all configured HEALTH_URLS at a fixed 30-second interval (configurable). Health events are logged to their own log group with full request/response detail.

• All endpoints probed concurrently each interval.
• Probe fires immediately at startup, then on each tick.
• Captures up to 64 KiB of response body; logs parsed body in health events.
• Reports response headers and cookies in health log events.
• HealthStatus=1 for HTTP 2xx–3xx; 0 for 4xx, 5xx, and transport errors.
• Traffic requests matching a health path are suppressed from traffic logs — they do not emit traffic metrics or log events.
• Health log events omit _q and app_name fields; they retain _t, request/response payloads, metadata, and EMF.

HEALTH_URLS

Flexible URL resolution

Each comma-separated entry in HEALTH_URLS may omit any combination of scheme, host, port, or path. Missing parts are filled from defaults.

scheme

Default: http. https supported.

host

Default: APP_HOST

port

First entry: APP_PORT. Later http: 80. https: 443.

path

Later entries without a path inherit the first entry path.

Operational Safety

Built for unattended operation

• ✓Panic recovery wraps every request handler goroutine and the health runner. A panic in one request returns 500 to the client and logs the recovered value; it never takes down the process.
• ✓Bounded body capture — body buffers have a hard 64 KiB ceiling. Memory use cannot grow unboundedly with large payloads.
• ✓Graceful shutdown — on SIGTERM or SIGINT, the server drains in-flight requests, then flushes the CloudWatch queue within a 10-second budget.
• ✓CloudWatch degradation — AWS config and sink initialization failures are logged to stderr; the proxy continues serving traffic and logging to stdout without interruption.
• ✓X-Forwarded-For preservation — inbound XFF headers from upstream load balancers are passed through and X-Forwarded-* is appended correctly.
• ✓No unbounded goroutine growth — the CloudWatch queue, batch sizes, and process tree walk are all bounded.

Deployment

Static binary, no runtime deps

Binaries are built with CGO_ENABLED=0. Drop them anywhere.

# verify download integrity
sha256sum -c SHA256SUMS

# Docker sidecar
docker run --rm --network host \
  -e APP_PORT=8080 -e PROXY_PORT=8081 \
  -e APP_NAME=my-app -e AWS_REGION=us-east-1 \
  ghcr.io/awsutils/cwproxy:latest