# AWS 账单数据工具

本目录包含 AWS 账单数据的统一导出和分析工具，支持多环境管理和多维度异常检测。

## 🚀 快速开始

### 1. 安装依赖
```bash
pip install google-cloud-bigquery requests pandas
```

### 2. 配置环境
```bash
# 设置 Google Cloud 认证
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

# 创建配置文件
cp config.json.example config.json
# 编辑 config.json，设置云级飞书 webhook 和阈值
```

### 3. 导出数据
```bash
# 导出所有环境最近一周数据
python aws_unified_billing_export.py --last-week

# 导出特定环境
python aws_unified_billing_export.py --env prod --days 30
```

### 4. 分析数据
```bash
# 分析并发送告警（默认分析前天数据）
python aws_unified_daily_analyzer.py --config config.json

# 测试模式（不发送通知）
python aws_unified_daily_analyzer.py --dry-run
```

## 📁 工具说明

### aws_unified_billing_export.py - 数据导出工具
从 BigQuery 导出 AWS 账单数据到 CSV 文件。

**主要功能：**
- 支持多环境（prod/nonprod/shared）
- 并发处理提高效率
- 智能缓存减少重复查询
- 自动处理错位生产账户

**常用命令：**
```bash
# 导出所有环境
python aws_unified_billing_export.py --last-week

# 导出生产环境
python aws_unified_billing_export.py --env prod --days 30

# 导出共享测试账户（含tag数据）
python aws_unified_billing_export.py --env shared --last-week

# 导出指定日期范围
python aws_unified_billing_export.py --start-date 2025-08-01 --end-date 2025-08-24

# 强制刷新缓存
python aws_unified_billing_export.py --refresh-cache --overwrite
```

### aws_unified_daily_analyzer.py - 异常分析工具
分析导出的账单数据，进行多维度异常检测并发送飞书告警。

**主要功能：**
- 账户维度费用异常检测
- 服务维度费用异常检测
- 新服务/停用服务检测
- 多环境独立阈值配置

**常用命令：**
```bash
# 分析所有环境
python aws_unified_daily_analyzer.py --config config.json

# 仅分析生产环境
python aws_unified_daily_analyzer.py --env prod

# 分析指定日期
python aws_unified_daily_analyzer.py --date 2025-08-15

# 分析特定账户
python aws_unified_daily_analyzer.py --env prod --account-id 730335266318

# 分别发送各环境报告
python aws_unified_daily_analyzer.py --separate-reports
```

## ⚙️ 配置说明

### 环境分类
- **nonprod**: 非生产环境账户
- **prod**: 生产环境账户  
- **shared**: 共享测试账户

### config.json 核心配置
```json
{
  "webhook_urls": {
    "cloud": "https://..."             // 云级AWS告警（统一通道）
  },
  "thresholds": {
    // 账户级别阈值
    "account_warning": 1.5,      // 150%触发警告
    "account_critical": 2.0,     // 200%触发严重
    
    // 服务级别阈值
    "service_warning": 2.0,      // 200%触发警告
    "service_critical": 3.0,     // 300%触发严重
    
    // 最小金额阈值
    "min_cost_threshold": 5.0,
    "new_service_threshold": 10.0
  }
}
```

**Webhook 说明**
- `cloud`：AWS 专属的云级告警通道，所有通知统一发送到该话题；已移除环境/场景级 webhook。
- `accountScopedServiceMonitor`：账户级服务监控专用话题群（可选，未配置则回落到 `cloud`）。
- `businessTypeSummary`：按标签业务类型成本汇总/漏打业务标签告警专用话题群（可选，未配置则回落到 `cloud`）。

- 所有告警（含区域、月度）均通过云级 webhook 发送。

**账户级服务监控（不可打标签，可选）**
- `settings.enableAccountScopedServiceMonitor`: 开启生产账户的账户级服务日报。
- `settings.accountScopedServiceMonitorServices`: 需要监控的服务列表（匹配账单中的服务名称）。
- `settings.accountScopedServiceMonitorEnvironments`: 默认只监控 `prod` 环境。

**漏打业务标签监控（tag_usedby/tag_servicetype）**
- `settings.enableUntaggedTagMonitor`: 开启漏打标签告警（出现即异常）。
- `settings.untaggedTagMonitorEnvironments`: 默认只监控 `prod` 环境。
- `settings.untaggedTagMonitorAccounts`: 仅监控指定账户（为空表示监控该环境全部账户）。
- `settings.untaggedTagMonitorMinCost`: 低于该金额的漏打标签成本将忽略，默认 0。
- `settings.untaggedTagMonitorIgnoredServices`: 忽略无法/无需打业务标签的全局服务。

**费用过滤（line_item_line_item_type）**
- `settings.awsLineItemTypeInclude`: 设置时仅保留这些类型（如 `Usage`, `SavingsPlanCoveredUsage`）。
- `settings.awsLineItemTypeExclude`: 未设置 include 时生效，用于排除不需要的类型。

**CUR 2.0 字段映射**
- `settings.awsCur2ProductField`: CUR 2.0 的服务字段（默认 `product_servicecode`）。
- `settings.awsCur2RegionField`: CUR 2.0 的区域字段（默认 `product_region_code`）。

**账户数据集与表映射（aws_account_details.csv）**
- `dataset_name`：账户所在的 BigQuery dataset。
- `table_name`：对应的账单表名；空值时默认 `{account_id}_aws_billing_data`。

## 📊 数据结构

### BigQuery 数据源

#### 数据集与表映射
- 以 `aws_account_details.csv` 的 `dataset_name` / `table_name` 为准
- `table_name` 为空时默认 `{account_id}_aws_billing_data`
- 默认 dataset：
  - nonprod/shared: `gcp-digital-bi.aws_nonprod_billing_native`
  - prod: `gcp-digital-bi.aws_prod_billing`
 - 2025-10-01 及以后统一从 `gcp-digital-bi.aws_billing_no_payer` 按月表读取（见 `settings.awsBillingCutoverDate` / `settings.awsBillingNoPayerDataset`）

### CSV 文件格式

#### 基础格式（nonprod）
```csv
date,account_id,environment,product,cost
2025-08-15,385595570414,nonprod,AmazonEC2,123.45
```

#### 完整格式（prod/shared）
```csv
date,account_id,environment,product,tag_component,tag_servicetype,region,tag_tenant,tag_usedby,cost
2025-08-15,385595570414,shared,AmazonEC2,,,us-west-2,,customer-tidb,953.89
```

### 输出目录结构
```
aws/
├── aws_account_details.csv              # 账户元数据
└── aws_billing_exports/                 # 所有环境数据
    ├── aws_{account_id}_{YYYY-MM}.csv
    ├── aws_prod_{account_id}_{YYYY-MM}.csv
    └── aws_shared_{account_id}_{YYYY-MM}.csv
```

## 🔄 定时任务配置

### Crontab 配置
```bash
# 每天早上 8 点导出前一天数据
0 8 * * * cd /path/to/project && python aws/aws_unified_billing_export.py --days 1

# 每天早上 9 点分析并发送告警
0 9 * * * cd /path/to/project && python aws/aws_unified_daily_analyzer.py --config aws/config.json

# 每周一导出上周数据
0 8 * * 1 cd /path/to/project && python aws/aws_unified_billing_export.py --last-week
```

## 🔍 故障排查

### 常见问题

1. **BigQuery 权限错误**
   ```bash
   # 验证BigQuery访问
   bq ls gcp-digital-bi:aws_nonprod_billing_native
   ```

2. **找不到数据文件**
   ```bash
   # 检查导出的文件
   ls -la aws_billing_exports/
   ```

3. **配置文件问题**
   ```bash
   # 验证JSON格式
   python -m json.tool aws/config.json
   ```

4. **账户分类错误**
   ```bash
   # 检查账户元数据
   cat aws_account_details.csv | grep account_id
   ```

## 📈 最佳实践

1. **数据导出**
   - 每日导出避免数据积压
   - 使用 `--exclude-recent-days` 处理账单延迟
   - 定期刷新缓存确保账户列表最新

2. **异常分析**
   - 根据环境特点调整阈值
   - 生产环境使用更严格的阈值
   - 定期审查和更新异常规则

3. **配置管理**
   - 使用版本控制管理配置文件
   - 云级 webhook 统一通道
   - 记录配置变更历史

4. **监控告警**
   - 设置脚本执行失败告警
   - 监控数据导出完整性
   - 跟踪告警发送成功率

## 🧪 测试验证

```bash
# 测试导出（仅1天数据）
python aws_unified_billing_export.py --days 1

# 测试分析（dry-run模式）
python aws_unified_daily_analyzer.py --dry-run

# 测试特定账户
python aws_unified_billing_export.py --env prod --account-id 730335266318 --days 1

# 验证配置
python -c "import json; json.load(open('config.json'))"
```

## 📝 详细文档

更多详细信息请参考：
- [配置指南](docs/CONFIG_GUIDE.md) - 错位账户配置详解