mirror of
https://github.com/Sea-Haven-Industries/front-sla-monitor.git
synced 2026-05-18 20:20:14 +00:00
fa2397cb5d
Restrict alerts to 8am-5pm ET Mon-Fri. Lambda skips before START_DATE (2026-05-14). First run of day with 2+ breaches sends consolidated summary to #front-sla-alerts. Cron narrowed to UTC 12-22 for DST coverage. README updated with new config and architecture.
114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
# front-sla-monitor
|
||
|
||
Scheduled Lambda that monitors Front conversations for SLA breaches and sends tiered Slack alerts. Runs every 15 minutes during business hours (8 AM–5 PM ET, Mon-Fri).
|
||
|
||
## SLA Rules
|
||
|
||
| Tier | Threshold | Action |
|
||
|---|---|---|
|
||
| 1 | 1 business hour without reply | Slack DM the assignee, or post to #front-sla-alerts if unassigned |
|
||
| 2 | 1 business day without reply | Slack DM Adam |
|
||
|
||
Business time counts weekday hours only (Mon-Fri, Eastern time). The SLA clock pauses on Saturday and Sunday.
|
||
|
||
Alerts are only sent during business hours (8 AM–5 PM ET). If breaches accumulate overnight, the first morning run sends a single summary message to #front-sla-alerts instead of individual alerts.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
EventBridge (every 15 min, 8 AM–5 PM ET, Mon-Fri)
|
||
│
|
||
▼
|
||
Lambda (Python 3.12, arm64)
|
||
│
|
||
├── Start date gate → skip before START_DATE
|
||
├── Business hours gate → skip outside 8 AM–5 PM ET
|
||
│
|
||
├── Secrets Manager → front-sla-monitor/front-api-token
|
||
├── Secrets Manager → front-sla-monitor/slack-bot-token
|
||
│
|
||
├── GET Front API /inboxes → filter to MONITOR_INBOXES
|
||
├── GET Front API /inboxes/{id}/conversations → open conversations (max 10 pages)
|
||
│
|
||
├── DynamoDB (front-sla-alerts) → dedup + first-run-of-day detection
|
||
│
|
||
├── Morning (first run) → summary message to #front-sla-alerts
|
||
├── Tier 1 → Slack DM assignee or #front-sla-alerts
|
||
└── Tier 2 → Slack DM Adam
|
||
```
|
||
|
||
## AWS Resources
|
||
|
||
- **Stack:** `front-sla-monitor` (SAM, us-east-1)
|
||
- **Lambda:** `front-sla-monitor` — Python 3.12, arm64, 128 MB, 300s timeout, 60-day log retention
|
||
- **DynamoDB:** `front-sla-alerts` — tracks alert history per conversation + monitor state, 7-day TTL
|
||
- **EventBridge:** `cron(0/15 12-22 ? * MON-FRI *)` — every 15 min during business hours (UTC range covers EDT/EST)
|
||
|
||
## Setup
|
||
|
||
### 1. Create the Slack App
|
||
|
||
1. Go to https://api.slack.com/apps and create **Front SLA Monitor**
|
||
2. Add Bot Token Scopes: `chat:write`, `users:read.email`
|
||
3. Install the app to your workspace and copy the Bot User OAuth Token
|
||
4. Create the `#front-sla-alerts` channel and invite the bot (`/invite @Front SLA Monitor`)
|
||
5. Copy the channel ID (right-click channel name > View channel details)
|
||
|
||
### 2. Create a Front API Token
|
||
|
||
1. Front > Settings > Developers > API tokens
|
||
2. Create a token with conversation read scope
|
||
3. Copy the token
|
||
|
||
### 3. Store Secrets in AWS
|
||
|
||
```bash
|
||
aws secretsmanager create-secret \
|
||
--name "front-sla-monitor/front-api-token" \
|
||
--secret-string "YOUR_FRONT_API_TOKEN" \
|
||
--region us-east-1
|
||
|
||
aws secretsmanager create-secret \
|
||
--name "front-sla-monitor/slack-bot-token" \
|
||
--secret-string "xoxb-YOUR-SLACK-BOT-TOKEN" \
|
||
--region us-east-1
|
||
```
|
||
|
||
### 4. Deploy
|
||
|
||
```bash
|
||
sam build
|
||
sam deploy --guided
|
||
```
|
||
|
||
Or push to `main` to trigger the GitHub Actions deploy workflow.
|
||
|
||
### 5. GitHub Actions Secrets
|
||
|
||
| Secret | Value |
|
||
|---|---|
|
||
| `AWS_DEPLOY_ROLE_ARN` | Org-wide OIDC deploy role (already configured) |
|
||
| `SAM_PARAMETER_OVERRIDES` | `FrontApiTokenSecretArn=arn:... SlackBotTokenSecretArn=arn:... SlackAlertChannel=CXXXXXXXXXX` |
|
||
|
||
## Manual Testing
|
||
|
||
```bash
|
||
aws lambda invoke --function-name front-sla-monitor --payload '{}' /dev/stdout --region us-east-1
|
||
```
|
||
|
||
Check logs:
|
||
|
||
```bash
|
||
aws logs tail /aws/lambda/front-sla-monitor --follow --region us-east-1
|
||
```
|
||
|
||
## Configuration
|
||
|
||
| Environment Variable | Default | Description |
|
||
|---|---|---|
|
||
| `ACK_SLA_MINUTES` | 60 | Business minutes before Tier 1 alert |
|
||
| `ACTION_SLA_MINUTES` | 1440 | Business minutes before Tier 2 alert |
|
||
| `ADAM_EMAIL` | adam@seahavenind.com | Tier 2 escalation recipient |
|
||
| `SLACK_ALERT_CHANNEL` | — | Channel ID for broadcast alerts |
|
||
| `MONITOR_INBOXES` | Triage,California,West Coast,Central,East Coast,Vendors | Comma-separated inbox names to monitor (empty = all shared) |
|
||
| `START_DATE` | 2026-05-14 | Date when monitoring begins (YYYY-MM-DD, Eastern time) |
|