Release/1.17.0

.github/docs/deploy/step-05-verify.md

@@ -102,6 +102,67 @@ In order of likelihood:
 
 ---
 
+### 6. Subscribe to Platform Alarms (required — not automated)
+
+The deploy creates one SNS topic that **every** CloudWatch alarm in the stack
+publishes to. It has no subscribers until you add them, so until you do this step
+the alarms change colour in the console and tell nobody.
+
+This is deliberately not infrastructure-as-code. Several teams usually need to
+hear about failures, and their membership changes far more often than the
+infrastructure does — requiring a pull request, a review, and a CloudFormation
+deploy to add one email address is how a notification list goes stale and stops
+being trusted. Subscribing is a one-line command that touches no code.
+
+Find the topic and subscribe:
+
+```bash
+PREFIX="your-project-prefix"   # the same CDK_PROJECT_PREFIX you deployed with
+
+TOPIC=$(aws ssm get-parameter \
+  --name "/${PREFIX}/observability/alarm-topic-arn" \
+  --query Parameter.Value --output text)
+
+aws sns subscribe \
+  --topic-arn "$TOPIC" \
+  --protocol email \
+  --notification-endpoint platform-team@example.edu
+```
+
+AWS sends a confirmation email; the subscription is inactive until the recipient
+clicks the link. Repeat for each address or distribution list.
+
+Other useful protocols:
+
+| Protocol | Use for |
+|---|---|
+| `email` | A team distribution list. Simplest, and enough for most forks. |
+| `https` | PagerDuty, Opsgenie, ServiceNow, or any webhook receiver. |
+| `sms` | Genuine paging. Costs per message. |
+| `lambda` | Custom routing, e.g. severity-based fan-out or Slack formatting. |
+
+Verify it took:
+
+```bash
+aws sns list-subscriptions-by-topic --topic-arn "$TOPIC" \
+  --query 'Subscriptions[].[Protocol,Endpoint,SubscriptionArn]' --output table
+```
+
+A `SubscriptionArn` of `PendingConfirmation` means the email has not been
+confirmed yet.
+
+Then open the health dashboard — `{PREFIX}-platform-health` in the CloudWatch
+console — and confirm the alarm-status row is populated and green. Row 1 tells
+you whether traffic is being served, row 2 tells you why, and row 3 lists every
+alarm's current state.
+
+> **Note on latency alarms:** the chat path uses server-sent events, so response
+> times of tens of seconds are normal for a healthy agent turn. Latency alarms are
+> deliberately set at 120 seconds. A *drop* in latency can actually mean turns are
+> failing early.
+
+---
+
 ## You're Done!
 
 Your AgentCore Public Stack is deployed and running. Here's what you have:

.github/workflows/platform.yml

@@ -207,6 +207,26 @@ jobs:
       # (default 100). Leave unset to take those defaults.
       CDK_MANAGED_KB_STORAGE_ALARM_GB: ${{ vars.CDK_MANAGED_KB_STORAGE_ALARM_GB }}
       CDK_MANAGED_KB_DAILY_COST_ALARM_USD: ${{ vars.CDK_MANAGED_KB_DAILY_COST_ALARM_USD }}
+      # Observability. All optional — unset means the default in config.ts.
+      # XRAY_SAMPLING_RATE is a rate (0.0-1.0), not a percentage.
+      CDK_OBSERVABILITY_ALARM_TOPIC_ENABLED: ${{ vars.CDK_OBSERVABILITY_ALARM_TOPIC_ENABLED }}
+      CDK_OBSERVABILITY_LOG_RETENTION_DAYS: ${{ vars.CDK_OBSERVABILITY_LOG_RETENTION_DAYS }}
+      CDK_OBSERVABILITY_ALB_TARGET_5XX_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_ALB_TARGET_5XX_THRESHOLD }}
+      CDK_OBSERVABILITY_ALB_P99_LATENCY_MS: ${{ vars.CDK_OBSERVABILITY_ALB_P99_LATENCY_MS }}
+      CDK_OBSERVABILITY_AGENTCORE_LATENCY_MS: ${{ vars.CDK_OBSERVABILITY_AGENTCORE_LATENCY_MS }}
+      CDK_OBSERVABILITY_AGENTCORE_ERROR_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_AGENTCORE_ERROR_THRESHOLD }}
+      CDK_OBSERVABILITY_LAMBDA_ERROR_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_LAMBDA_ERROR_THRESHOLD }}
+      CDK_OBSERVABILITY_LAMBDA_DURATION_PERCENT_OF_TIMEOUT: ${{ vars.CDK_OBSERVABILITY_LAMBDA_DURATION_PERCENT_OF_TIMEOUT }}
+      CDK_OBSERVABILITY_DYNAMO_THROTTLE_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_DYNAMO_THROTTLE_THRESHOLD }}
+      CDK_OBSERVABILITY_ECS_CPU_PERCENT: ${{ vars.CDK_OBSERVABILITY_ECS_CPU_PERCENT }}
+      CDK_OBSERVABILITY_ECS_MEMORY_PERCENT: ${{ vars.CDK_OBSERVABILITY_ECS_MEMORY_PERCENT }}
+      CDK_OBSERVABILITY_XRAY_SAMPLING_RATE: ${{ vars.CDK_OBSERVABILITY_XRAY_SAMPLING_RATE }}
+      CDK_OBSERVABILITY_XRAY_SAMPLING_RESERVOIR: ${{ vars.CDK_OBSERVABILITY_XRAY_SAMPLING_RESERVOIR }}
+      CDK_OBSERVABILITY_XRAY_INSIGHTS_NOTIFICATIONS: ${{ vars.CDK_OBSERVABILITY_XRAY_INSIGHTS_NOTIFICATIONS }}
+      CDK_OBSERVABILITY_AGENTCORE_APPLICATION_LOGS_ENABLED: ${{ vars.CDK_OBSERVABILITY_AGENTCORE_APPLICATION_LOGS_ENABLED }}
+      CDK_OBSERVABILITY_PROMPT_CACHE_AVOIDABLE_MISS_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_PROMPT_CACHE_AVOIDABLE_MISS_THRESHOLD }}
+      CDK_OBSERVABILITY_PROMPT_CACHE_WASTED_USD_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_PROMPT_CACHE_WASTED_USD_THRESHOLD }}
+      CDK_OBSERVABILITY_PROMPT_CACHE_SESSION_WASTED_USD_THRESHOLD: ${{ vars.CDK_OBSERVABILITY_PROMPT_CACHE_SESSION_WASTED_USD_THRESHOLD }}
       # Secrets
       AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
       AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}