burncloud-aws 0.1.0

# AWS Bedrock 429 监控系统部署指南

本指南详细说明了如何部署 AWS Bedrock API 的 429 错误监控系统，包括所需的权限、架构组件和具体操作步骤。

## 系统架构概览

这是一个完整的 AWS Bedrock 监控系统，专门用于监控 429 (Too Many Requests) 错误：

### 监控数据流程
1. **CloudTrail** → **EventBridge** → **Lambda** → **CloudWatch Logs** (API 调用监控)
2. **CloudWatch Metrics** → **Alarms** → **SNS** → **Lambda** (阈值监控和告警)
3. **Lambda** → **CloudWatch Logs** (详细的请求/响应日志记录)

### 核心组件
- **AWS Lambda**: 处理监控事件的主要计算服务
- **CloudWatch**: 指标收集、告警和日志存储
- **EventBridge**: 事件路由和处理
- **CloudTrail**: API 调用审计
- **SNS**: 告警通知服务
- **IAM**: 权限管理

## 必需的 AWS 权限

### 1. IAM 权限 (用于创建角色和策略)
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRole",
                "iam:DetachRolePolicy",
                "iam:DeleteRolePolicy"
            ],
            "Resource": "arn:aws:iam::*:role/lambda-bedrock-monitor-role*"
        }
    ]
}
```

### 2. Lambda 权限 (函数执行权限)
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lambda:CreateFunction",
                "lambda:GetFunction",
                "lambda:GetFunctionConfiguration",
                "lambda:UpdateFunctionCode",
                "lambda:UpdateFunctionConfiguration",
                "lambda:DeleteFunction",
                "lambda:AddPermission",
                "lambda:InvokeFunction",
                "lambda:PublishVersion"
            ],
            "Resource": [
                "arn:aws:lambda:*:*:function:bedrock-monitor-function",
                "arn:aws:lambda:*:*:function:bedrock-monitor-function:*"
            ]
        }
    ]
}
```

### 3. CloudWatch 权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudwatch:PutMetricAlarm",
                "cloudwatch:DeleteAlarms",
                "cloudwatch:DescribeAlarms",
                "cloudwatch:GetMetricData",
                "cloudwatch:ListMetrics"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams"
            ],
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}
```

### 4. EventBridge 权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "events:PutRule",
                "events:DeleteRule",
                "events:DescribeRule",
                "events:PutTargets",
                "events:RemoveTargets",
                "events:ListTargetsByRule"
            ],
            "Resource": "arn:aws:events:*:*:rule/bedrock-api-monitor-rule"
        }
    ]
}
```

### 5. CloudTrail 权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudtrail:CreateTrail",
                "cloudtrail:DeleteTrail",
                "cloudtrail:DescribeTrails",
                "cloudtrail:GetTrailStatus",
                "cloudtrail:StartLogging",
                "cloudtrail:StopLogging",
                "cloudtrail:UpdateTrail",
                "cloudtrail:PutEventSelectors",
                "cloudtrail:GetEventSelectors"
            ],
            "Resource": "*"
        }
    ]
}
```

### 6. S3 权限 (用于 CloudTrail 日志存储)
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:DeleteBucket",
                "s3:HeadBucket",
                "s3:PutBucketPolicy",
                "s3:GetBucketPolicy",
                "s3:DeleteBucketPolicy"
            ],
            "Resource": "arn:aws:s3:::bedrock-cloudtrail-logs-*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::bedrock-cloudtrail-logs-*/*"
        }
    ]
}
```

### 7. SNS 权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:CreateTopic",
                "sns:DeleteTopic",
                "sns:Subscribe",
                "sns:Unsubscribe",
                "sns:Publish",
                "sns:SetTopicAttributes",
                "sns:GetTopicAttributes"
            ],
            "Resource": "arn:aws:sns:*:*:bedrock-throttling-alerts"
        }
    ]
}
```

## 部署 Lambda 函数的 IAM 角色

系统会自动创建以下 IAM 角色：`lambda-bedrock-monitor-role`

### 托管策略
- `arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole`
- `arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole`

### 内联策略

#### 1. CloudWatch Logs 写权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams"
            ],
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}
```

#### 2. 凭据管理权限 (用于 429 错误时禁用访问密钥)
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:UpdateAccessKey",
                "iam:ListAccessKeys",
                "iam:GetAccessKeyLastUsed",
                "iam:GetUser"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:RequestedRegion": ["ap-northeast-1", "ap-southeast-1", "ap-southeast-2"]
                }
            }
        }
    ]
}
```

#### 3. SNS 通知权限
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:Publish"
            ],
            "Resource": "arn:aws:sns:*:*:bedrock-throttling-alerts"
        }
    ]
}
```

## 具体部署步骤

### 前置条件
1. **AWS CLI 配置**: 确保已配置有效的 AWS 凭证
2. **权限验证**: 确保部署用户具有上述所有权限
3. **区域选择**: 推荐使用 `us-east-1` 或 `ap-northeast-1`

### 步骤 1: 环境准备
```bash
# 克隆或下载项目代码
cd burncloud-aws

# 配置环境变量 (.env 文件)
cat > .env << EOF
AWS_ACCESS_KEY_ID=你的访问密钥ID
AWS_SECRET_ACCESS_KEY=你的秘密访问密钥
AWS_REGION=us-east-1
RUST_LOG=info
EOF
```

### 步骤 2: 编译项目
```bash
# 安装 Rust (如果尚未安装)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 编译项目
cargo build
```

### 步骤 3: 部署 Lambda 函数
```bash
# 清理可能冲突的环境变量
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION

# 部署 Lambda 监控系统
cargo run --bin deploy_lambda
```

此步骤会执行：
1. 创建 IAM 角色 `lambda-bedrock-monitor-role`
2. 附加必要的权限策略
3. 创建 Lambda 函数 `bedrock-monitor-function`
4. 部署 Python 监控代码

### 步骤 4: 设置 CloudTrail (用于 API 调用监控)
```bash
# 注意：此步骤需要在源代码中启用相应的函数
# 目前代码中有 setup_cloudtrail_for_bedrock() 方法
```

系统会创建：
1. S3 存储桶：`bedrock-cloudtrail-logs-{account-id}`
2. CloudTrail 路径：`bedrock-api-monitoring-trail`
3. 数据事件配置，专门监控 Bedrock 服务

### 步骤 5: 配置 EventBridge 规则
系统会自动创建：
1. 规则名称：`bedrock-api-monitor-rule`
2. 事件模式：监控 AWS Bedrock API 调用
3. 目标：Lambda 函数 `bedrock-monitor-function`

监控的事件类型：
- `InvokeModel`
- `Converse`
- `InvokeModelWithResponseStream`

### 步骤 6: 设置 CloudWatch 告警
```bash
# 创建错误率告警
cargo run --bin cloudwatch_alarm_setup
```

系统会创建多个告警：
1. **Lambda 错误率告警**: 监控函数执行错误
2. **429 错误计数告警**: 专门监控 Bedrock 429 错误
3. **响应时间告警**: 监控 API 响应时间
4. **并发限制告警**: 监控并发使用情况

### 步骤 7: 配置 SNS 通知
```bash
# 设置 SNS 到 Lambda 的集成
cargo run --bin sns_lambda_setup
```

创建：
1. SNS 主题：`bedrock-throttling-alerts`
2. 订阅：Lambda 函数作为订阅者

### 步骤 8: 验证部署
```bash
# 测试 Lambda 函数调用
cargo run --bin test_lambda_invoke

# 测试 SNS 告警
cargo run --bin test_sns_alarm
```

## 监控特性

### 1. API 调用监控
- **监控范围**: 所有 Bedrock API 调用
- **重点监控**: 429 错误和成功请求
- **数据记录**: 请求时间、模型、错误码、响应时间

### 2. 自动响应机制
当检测到 429 错误时，系统可以：
1. **自动禁用访问密钥**: 在指定区域禁用受影响的 AK/SK
2. **发送告警通知**: 通过 SNS 发送实时告警
3. **记录详细信息**: 在 CloudWatch Logs 中记录完整的错误上下文

### 3. 数据脱敏
系统自动脱敏敏感信息：
- AWS 访问密钥
- Bearer tokens
- 邮箱地址
- 电话号码
- 信用卡号码

### 4. 多级日志记录
- **Full**: 完整的请求/响应信息（脱敏后）
- **Summary**: 关键指标摘要
- **Partial**: 部分详细信息

## 故障排查

### 常见问题

#### 1. IAM 角色创建失败
- **检查权限**: 确保有 `iam:CreateRole` 权限
- **检查区域**: 确保在支持的区域中部署

#### 2. Lambda 函数创建失败
- **检查 ZIP 内容**: 确保代码语法正确
- **检查角色**: 确保 IAM 角色已正确创建

#### 3. CloudTrail 配置失败
- **检查 S3 权限**: 确保 S3 存储桶创建权限
- **检查服务限制**: 确保未超过 CloudTrail 数量限制

#### 4. 环境变量冲突
- **清理系统环境变量**: 使用 `unset` 清理可能冲突的 AWS 环境变量
- **使用 .env 文件**: 确保程序使用正确的配置

### 日志查看位置
- **Lambda 执行日志**: `/aws/lambda/bedrock-monitor-function`
- **详细监控日志**: `/aws/lambda/bedrock-monitor-function/detailed`
- **CloudTrail 日志**: S3 存储桶 `bedrock-cloudtrail-logs-{account-id}`

## 成本估算

### 月成本预估（基于常规使用）
- **Lambda**: ~$0.20 (100万次调用)
- **CloudWatch Logs**: ~$0.50 (5GB日志存储)
- **CloudWatch Alarms**: ~$3.00 (6个告警)
- **CloudTrail**: ~$2.00 (1个trail + 数据事件)
- **SNS**: ~$0.10 (1000次通知)
- **S3**: ~$0.23 (1GB存储)

**总计**: ~$6.03/月

## 安全考虑

1. **最小权限原则**: IAM 角色只包含必要的权限
2. **数据脱敏**: 自动移除敏感信息
3. **区域限制**: 凭据管理仅限指定区域
4. **访问控制**: 确保只有授权人员可以修改配置

## 维护和更新

### 定期任务
1. **检查日志**: 定期查看 CloudWatch Logs
2. **更新代码**: 根据需要更新监控逻辑
3. **调整阈值**: 根据实际使用调整告警阈值
4. **清理资源**: 定期清理不再使用的资源

### 扩展功能
- 添加更多告警类型
- 集成其他通知渠道（Slack、Teams等）
- 添加自动恢复机制
- 实现更智能的限流策略

---

**注意**: 在生产环境部署前，请务必在测试环境中完整验证所有功能，并根据实际需求调整配置参数。