@auth-craft/aws-cf-stack 1.8.0 → 1.9.0

package/.env.example

@@ -155,6 +155,18 @@ LAMBDA_REFRESH_COOKIE_TENANT=refresh_token_tenant
 LAMBDA_REFRESH_COOKIE_SYSTEM=refresh_token_system
 LAMBDA_AUDIT_ENABLED=false
 LAMBDA_DEVICE_TRACKING=true
+
+# ─── Observability cost controls (optional) ──────────────────────────────────
+# CloudWatch Logs are billed for ingestion AND stored volume; retention only affects
+# storage. Short retention in dev is the cheap default.
+#   Unset  → 3 days in dev, 30 days in staging/prod.
+#   Valid  → 1,3,5,7,14,30,60,90,120,150,180,365,400,545,731,1096,1827,2192,2557,
+#            2922,3288,3653  (CloudWatch's fixed set — anything else fails at synth),
+#            or 'infinite' to never expire.
+LAMBDA_LOG_RETENTION_DAYS=
+# X-Ray tracing is billed per recorded trace. Unset → disabled in dev, active otherwise.
+#   active | disabled | pass_through
+LAMBDA_TRACING=
 LAMBDA_APP_URL=
 LAMBDA_SUPPORT_EMAIL=
 LAMBDA_CORS_ORIGINS=

package/README.md

@@ -163,6 +163,43 @@ CF_EDGE_GATE_SECRET="$SNAP_EDGE" CLOUDFLARE_ACCOUNT_ID="$SNAP_CF_ACCT" \
   npx auth-craft-stack all --stage "$STAGE"
 ```
 
+## Observability cost controls (log retention, tracing)
+
+CloudWatch Logs and X-Ray are usually the two line items that make a low-traffic **dev**
+stage cost more than the Lambda itself. Both are configurable, with stage-aware defaults
+that keep dev cheap without touching staging/prod behaviour:
+
+| Setting | Env var / flag | Default (dev) | Default (staging/prod) |
+|---------|----------------|---------------|------------------------|
+| Log retention | `LAMBDA_LOG_RETENTION_DAYS` / `--log-retention-days` | `3` days | `30` days |
+| X-Ray tracing | `LAMBDA_TRACING` / `--tracing` | `disabled` | `active` |
+
+```bash
+# Cheapest dev: keep 1 day of logs, no tracing (tracing is already off by default in dev)
+npx auth-craft-stack lambda --stage dev --log-retention-days 1
+
+# Turn tracing back on in dev while debugging
+npx auth-craft-stack lambda --stage dev --tracing active
+
+# Long retention for an audited prod
+npx auth-craft-stack lambda --stage prod --log-retention-days 365
+```
+
+Notes:
+- Retention accepts only **CloudWatch's fixed set** — `1, 3, 5, 7, 14, 30, 60, 90, 120, 150,
+  180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653` — or `infinite` to never
+  expire. Any other value fails at **synth** time with the valid list, so a typo can't
+  silently deploy the wrong retention.
+- Retention caps **storage** cost only; you are still billed for log **ingestion**. To cut
+  ingestion, reduce what the app logs.
+- Changing retention applies to the existing log group too (it's the same CloudFormation
+  resource), so old logs beyond the new window age out — it is not just for new logs.
+- In `prod` the log group has `RemovalPolicy.RETAIN`, so destroying the stack keeps the logs
+  (and the group must be deleted manually before a same-name redeploy). In dev/staging it is
+  destroyed with the stack.
+- `LogRetentionDays` and `TracingMode` are emitted as CDK outputs, so
+  `npx auth-craft-stack outputs` shows what is actually deployed.
+
 ## CORS (per scope + dynamic allowlist)
 
 CORS is resolved **per scope** (system / tenant / customer) — the 3 workers no longer