使用 Amazon Athena 分析 Kiro 团队用量报表：动态模型列的数据建模实践

摘要：本文介绍了如何使用 Amazon Athena 对 Kiro 提供的 per-user activity 报表进行分析。

01 一、背景：AI 开发工具规模化使用之后的用量观测诉求

02 二、Kiro 提供的 per-user activity 报表

03 三、方案选择：Amazon Athena

04 四、数据建模的关键挑战：动态模型列

05 五、整体架构

06 六、ETL 实现

07 七、Athena 建表与 Partition Projection

08 八、DDL 实践注意事项

09 九、典型分析查询

10 十、接入 Amazon Quick 构建用量看板

11 十一、运行成本与运维

12 十二、总结

一、背景：AI 开发工具规模化使用之后的用量观测诉求

随着 AI 辅助开发工具在工程团队中铺开，越来越多的客户会面临一个共同的问题：当一个团队几十人都在使用付费 AI 开发工具时，如何系统化地观测每位工程师的使用情况？

这并不是一个抽象的诉求，而是源自几个非常具体的业务问题：

额度治理：团队的订阅 credit 每月有上限，谁在快速消耗，谁基本闲置？是否需要在月度结算前重新分配？
模型选择：团队成员各自习惯用什么模型？高消耗的用户是否选择了与其任务匹配的模型？
能力推广：哪些同事已经形成了高频使用习惯？哪些同事还需要培训和案例分享去带动？
超额预警：开启了 overage 的用户离套餐上限还有多远？要不要提前介入避免超支？

这些问题如果只靠每月一封订阅账单，是无法回答的。需要的是按天、按用户、按模型的明细数据，并以 SQL 和报表的形式可持续地分析。

二、Kiro 提供的 per-user activity 报表

Amazon 推出的 AI IDE Kiro 在企业订阅之后，提供了每用户每天粒度的用量明细报表。报表会自动每天投递到客户指定的 S3 桶中，路径形如：

s3://<your-bucket>/data/AWSLogs/<account-id>/KiroLogs/user_report/
    <region>/<yyyy>/<mm>/<dd>/00/KIRO_IDE_<account-id>_user_report_<ts>.csv

每个 CSV 文件包含的字段大致分为两类。

静态字段：报表日期、用户 ID、订阅档位（PRO / PRO_PLUS / PRO_MAX / POWER）、当日对话数、当日总消息数、credit 消耗、overage 上限与已用、是否首次激活、用户邮箱等共 13 列。

动态字段：用户当日在各个模型上的消息数。例如 claude_opus_4.7_messages、claude_sonnet_4_messages 等。

数据已经在客户自己的 S3 桶里，下一步是把它接入分析层，对外提供 SQL 查询能力。

三、方案选择：Amazon Athena

针对这个场景，我们选择了 Amazon Athena 作为分析引擎，主要基于以下三点考量。

第一，数据规模和访问频率匹配 Serverless 模式。每个客户端类型每天产出的 CSV 通常在几 KB 到几十 KB 之间，整月数据量在百 KB 量级。建一个常驻数据仓库（如 Redshift）的固定成本远超过这部分数据本身的价值。Athena 按扫描数据量计费，在这种小数据场景下单次查询费用低廉。

第二，S3 原地查询，无需数据搬迁。报表本身就在 S3 上，Athena 可以直接对 S3 上的对象建外部表，省去任何 ingestion 流程。

第三，Partition Projection 支持新分区零运维。报表每天都会落新分区，使用 Partition Projection 后无需运行 MSCK REPAIR TABLE 或额外维护 Glue Crawler。

四、数据建模的关键挑战：动态模型列

最直观的实现方式，是直接基于 raw CSV 用 OpenCSVSerDe 建一张外部表。所有字段一对一映射，配合 Partition Projection 即可完成。

但仔细阅读 Kiro 官方文档会发现一段重要描述：

Model message column names are the model names in lower case in alphabetical order, starting with Auto.

也就是说，CSV 中的「模型消息数」列是动态的，按字母序排列。今天用户只用了 claude_opus_4.7，CSV 的第 14 列是 claude_opus_4.7_messages；当某天 Kiro 新增了 auto 模式并有人开始使用，按字母序 auto_messages 会被插入到 claude_opus_4.7_messages 之前，第 14 列变为 auto_messages。

而 OpenCSVSerDe 是按列位置而非列名做映射的。一旦动态列发生漂移，旧分区与新分区在同一张表的 schema 下，相同位置的列会代表不同的模型，造成数据语义错位，并且不会有任何运行时报错。

为避免这一隐患，我们调整方案：在 Athena 之前增加一层轻量级 ETL，把宽表展开为长表，将「模型」这个维度从列转为行，从而使下游 schema 始终保持稳定。

五、整体架构

Raw CSV
  s3://<your-bucket>/data/AWSLogs/<account-id>/KiroLogs/user_report/
      <region>/<yyyy>/<mm>/<dd>/00/<CLIENT>_<account-id>_user_report_<ts>.csv
        │
        │   ETL: scripts/etl_kiro_user_activity.py
        │   (Python + boto3 + pyarrow)
        ▼
Curated Parquet（Hive 风格分区）
  s3://<your-bucket>/curated/fact_user_day/region=.../year=.../month=.../day=.../<CLIENT>.parquet
  s3://<your-bucket>/curated/fact_user_day_model/region=.../year=.../month=.../day=.../<CLIENT>.parquet
        │
        │   Amazon Athena 外部表 + Partition Projection
        ▼
Athena SQL：
  kiro_analytics.fact_user_day
  kiro_analytics.fact_user_day_model

设计要点：

两张事实表：fact_user_day 保留每用户每天一行的静态字段；fact_user_day_model 为每用户每天每模型一行的 long format。模型从列转为行后，schema 不再依赖上游列序。
Parquet + Snappy 压缩：列存格式扫描效率高，存储占用小，适合 Athena 这类按扫描量计费的查询引擎。
Hive 风格分区路径：配合 Partition Projection 模板自动识别新分区，无需手动注册。

六、ETL 实现

ETL 脚本的核心逻辑是遍历 raw CSV，先按固定的前 13 列构造 fact_user_day 的记录，再将后续所有 *_messages 列展开成 fact_user_day_model 的多行：

STATIC_HEADER = [
    "Date", "UserId", "Client_Type",
    "Chat_Conversations", "Credits_Used",
    "Overage_Cap", "Overage_Credits_Used", "Overage_Enabled",
    "ProfileId", "Subscription_Tier", "Total_Messages",
    "New_User", "User_Email",
]

def process_csv(csv_bytes, key):
    reader = csv.reader(io.StringIO(csv_bytes.decode("utf-8-sig")))
    header = next(reader)

    # 校验静态前缀，防止上游 schema 变更被忽略
    for i, expected in enumerate(STATIC_HEADER):
        if header[i] != expected:
            raise ValueError(f"{key}: header drift at col {i}")

    model_columns = header[len(STATIC_HEADER):]  # 动态模型列
    static_rows, model_rows = [], []

    for row in reader:
        rec = dict(zip(header, row))
        static_rows.append({
            "report_date": to_date(rec["Date"]),
            "user_email": rec["User_Email"],
            # ... 其他静态字段
        })
        for col in model_columns:
            if (v := to_int(rec.get(col))) is None:
                continue
            model_rows.append({
                "report_date": to_date(rec["Date"]),
                "user_email": rec["User_Email"],
                "model_name": col[:-len("_messages")],
                "messages": v,
            })
    return static_rows, model_rows

输出按分区路径写入 S3：

key = (
    f"curated/fact_user_day_model/"
    f"region={p.region}/year={p.year}/month={p.month}/day={p.day}/"
    f"{p.client}.parquet"
)
pq.write_table(table, buf, compression="snappy")
s3.put_object(Bucket=dest_bucket, Key=key, Body=buf.getvalue())

由于相同分区 + 相同客户端类型会生成相同 Key，重跑会原位覆盖，脚本具备幂等性。25 个 CSV 全量执行一次约几秒钟完成。

七、Athena 建表与 Partition Projection

fact_user_day_model 的建表语句如下，fact_user_day 结构同理：

CREATE EXTERNAL TABLE kiro_analytics.fact_user_day_model (
  report_date  date,
  user_id      string,
  client_type  string,
  user_email   string,
  model_name   string,
  messages     bigint
)
PARTITIONED BY (region string, year string, month string, day string)
STORED AS PARQUET
LOCATION 's3://<your-bucket>/curated/fact_user_day_model/'
TBLPROPERTIES (
  'projection.enabled'        = 'true',
  'projection.region.type'    = 'enum',
  'projection.region.values'  = 'us-east-1',
  'projection.year.type'      = 'integer',
  'projection.year.range'     = '2026,2030',
  'projection.year.digits'    = '4',
  'projection.month.type'     = 'integer',
  'projection.month.range'    = '1,12',
  'projection.month.digits'   = '2',
  'projection.day.type'       = 'integer',
  'projection.day.range'      = '1,31',
  'projection.day.digits'     = '2',
  'storage.location.template' =
    's3://<your-bucket>/curated/fact_user_day_model/region=${region}/year=${year}/month=${month}/day=${day}/'
);

Partition Projection 的优势在于新分区自动可见——Athena 会根据查询谓词中的 year、month、day 按模板拼出 S3 路径直接读取，不再需要任何分区注册操作。对于这种「每天产出一个新分区、写入路径永远在向前推进」的报表场景，这是最贴合的方案。

八、DDL 实践注意事项

在落地过程中有几点 Athena 行为值得记录：

Date 是 SQL 保留字。原始 CSV 第一列字段名为 Date，建表时必须重命名（这里改为 report_date），否则后续查询无法引用。
列名不能包含点号。原始 CSV 中存在形如 claude_opus_4.7_messages 的列名（点号来自模型版本号），Athena 不允许此类列名。本方案在 ETL 阶段将其转换为 model_name 字段，从根本上规避了这一限制。
Athena 单次提交只能执行一条 DDL。在 Athena Console 中粘贴多条 CREATE TABLE 同时执行会报语法错误。批量执行时建议在脚本中按 ; 拆分后逐条调用 StartQueryExecution。
CREATE DATABASE 时 QueryExecutionContext 不能指定目标库——库尚不存在。首条 DDL 应使用 default 数据库作为执行上下文。
DDL 中谨慎使用行内注释。在某些复制粘贴场景下，– 单行注释若与后续语法符号同处一行，可能导致解析异常。建议将注释置于 DDL 语句块之外。
跨区域访问会引入额外开销。如果 S3 桶位于 us-east-1 而本地 AWS CLI 默认 region 为其他区域，boto3 会发生一次 301 重定向并重新签名。建议在脚本默认 region 中显式指定与 S3 桶相同的区域。

九、典型分析查询

接入后即可使用标准 SQL 回答开篇提出的几个业务问题。

每人每月用量汇总：

SELECT user_email,
       MAX(subscription_tier)        AS tier,
       COUNT(DISTINCT report_date)   AS active_days,
       SUM(total_messages)           AS messages,
       ROUND(SUM(credits_used), 2)   AS credits
FROM kiro_analytics.fact_user_day
WHERE year = '2026' AND month = '06'
GROUP BY user_email
ORDER BY credits DESC;

每日活跃用户与消息趋势：

SELECT report_date,
       COUNT(DISTINCT user_id)  AS active_users,
       SUM(total_messages)      AS messages,
       SUM(credits_used)        AS credits
FROM kiro_analytics.fact_user_day
WHERE year = '2026' AND month = '06'
GROUP BY report_date
ORDER BY report_date;

模型使用分布（按月按人）：

SELECT user_email, model_name, SUM(messages) AS messages
FROM kiro_analytics.fact_user_day_model
WHERE year = '2026' AND month = '06'
GROUP BY user_email, model_name
ORDER BY user_email, messages DESC;

Overage 监控：

SELECT report_date, user_email,
       overage_cap, overage_credits_used,
       ROUND(overage_credits_used / NULLIF(overage_cap, 0) * 100, 1) AS overage_pct
FROM kiro_analytics.fact_user_day
WHERE overage_enabled = true
  AND year = '2026' AND month = '06'
ORDER BY overage_pct DESC;

十、接入 Amazon Quick 构建用量看板

Athena 让上面的 SQL 可以随时跑，但对非工程角色（团队负责人、财务、行政）来说 SQL 依然不友好。把结果沉到 Amazon Quick 看板上，才算真正把用量数据变成团队日常可用的资产。

Amazon Quick 就是原来的 Amazon QuickSight——2025 年先更名为 Quick Suite，之后简化为 Amazon Quick，从纯 BI 演进为分析 + AI 一体的平台。老的 QuickSight API / SDK / IAM 角色名保持向后兼容，控制台入口现在是 Amazon Quick。

Amazon Quick 与 Athena 是同一 Region 内的原生集成，接入过程分三步：先授权、再建数据源与数据集、最后拼 Dashboard。

10.1 授权 Amazon Quick 访问 Athena 与 S3

首次使用需要在 Amazon Quick 管理页面授权对应的 AWS 服务：

1. Amazon Quick 控制台右上角进入 Manage Quick → Security & permissions。

2. 在 Quick access to AWS services 中点 Manage，勾选 Amazon Athena。

3. 弹出的 S3 授权面板里点 Select S3 buckets，选中放 curated Parquet 的桶，以及 Athena 查询结果输出桶（s3://<your-bucket>/athena-results/），同时勾选 Write permission for Athena Workgroup。

若 Amazon Quick 尚未订阅，需要先在 Athena 所在 Region 完成开通——Quick 是按 Region 独立开通的，跨 Region 访问会失败。

10.2 添加 Athena 数据源与数据集

回到 Amazon Quick 主页 → Datasets → New dataset → Athena

Data source name：kiro-athena
Athena workgroup：primary
点击 Validate connection 通过后 Create data source。

在数据源之上分别为两张 Athena 表建 Dataset：

fact_user_day：选择数据库 kiro_analytics → 表 fact_user_day → Import to SPICE。数据量极小，SPICE 加载与刷新几乎无耗时，交互体验也比 Direct query 好。
fact_user_day_model：同理。

两张表都建成独立 Dataset，不在 Quick 层做 JOIN。原因是 fact_user_day_model 是长表，一个 user-day 会展开成多行；如果与 fact_user_day 拉平 JOIN，credits_used / total_messages 这类静态度量在同一 user-day 会被复制多份，直接 SUM 就会被模型行数放大。让每张 Dataset 只承担各自维度的度量，是最不容易出错的做法。

SPICE 数据集在 Dataset → Refresh 里可以配置每日增量刷新。ETL 通常在 UTC 02:00 之后完成，把 SPICE 刷新排在 UTC 03:00 是安全窗口。

10.3 构建 Analysis 与 Dashboard

新建 Analysis 时先加入 fact_user_day，进入编辑器后通过左侧 Add dataset 再引入 fact_user_day_model。每个 visual 创建时选择所需 Dataset 即可。

下面这五张 visual 已经覆盖开篇提出的所有业务问题：

Visual	Dataset	类型	主要字段
月度 KPI（总消息 / 总 credits / 活跃用户数）	fact_user_day	KPI	度量：SUM(total_messages)、SUM(credits_used)、COUNTD(user_id)
每日消息与活跃用户趋势	fact_user_day	Line chart	X：report_date（DAY 粒度）；Y：SUM(total_messages)、COUNTD(user_id)
每人月度用量 Top N	fact_user_day	Horizontal bar chart	Y：user_email；Value：SUM(credits_used)；Group/Color：subscription_tier
每日模型消息分布	fact_user_day_model	Stacked column chart	X：report_date；Value：SUM(messages)；Group/Color：model_name
Overage 监控	fact_user_day	Table	列：report_date、user_email、overage_cap、overage_credits_used；Filter：overage_enabled = true

再在页面顶部添加几个 Sheet controls 作为全局过滤器：

Date range：绑定 report_date 字段。
Subscription tier：多选下拉，绑定 subscription_tier。
Client type：绑定 client_type，用来在 KIRO_IDE / KIRO_CLI / PLUGIN 之间切换。

配置完成后，右上角 Share → Publish dashboard，命名为 Kiro Team Usage，把访问权限授予团队即可。之后每天 ETL 跑一次、SPICE 按计划刷新，Dashboard 会自动反映最新数据，无需人工介入。

10.4 常见坑

QuickSight 看不到 kiro_analytics 数据库：多半是没在 Manage QuickSight → Security & permissions 里勾选 Athena，或者 curated 桶没在授权列表里。补上之后在 Dataset 创建页刷新即可。
Dashboard 打开报 Insufficient permissions on S3：Athena 查询结果输出桶忘记授权。在 Security & permissions 里加入 s3://<your-bucket>/athena-results/ 并同时勾选 Write permission。
SPICE 刷新失败：常见于 Athena Workgroup 或 curated 桶启用了 CMK 加密，但 QuickSight 的服务角色没有 KMS 权限。给 QuickSight service role 加对应 KMS Key 的 Decrypt 权限即可。
跨 Region 建 Dataset 报错：确认 QuickSight 当前 Region 与 Athena、S3 桶在同一 Region。切换 Region 后需要重新完成 Security & permissions 授权。

十一、运行成本与运维

整套方案运行一个月后的实际资源消耗：

累计处理 CSV 文件 25 份，curated 后 Parquet 文件总大小约 31 KB
ETL 全量重跑一次耗时约 5 秒
单次月度汇总查询 Athena 扫描数据量 31 KB，单次查询费用低廉（远低于 Athena 10 MB 最小计费单元）
日常使用下，S3 存储成本与 Athena 查询成本相加低于 1 USD/月

后续可将 ETL 脚本部署为 AWS Lambda，配合 Amazon EventBridge Scheduler 每天定时触发，使整条数据链路完全 Serverless 化。IAM 角色仅需 raw 桶的读权限和 curated 桶的写权限。

十二、总结

本文介绍了如何使用 Amazon Athena 对 Kiro 提供的 per-user activity 报表进行分析。核心实践有三点：

从上游文档出发评估数据建模。CSV 看似简单结构，但「模型列按字母序动态新增」这一上游特性会让 OpenCSVSerDe 在未来发生静默错位。在 ETL 阶段将动态维度从列转为行，是让下游 schema 长期稳定的关键。
Parquet + Partition Projection 是 Athena 上小数据分析的合理默认。即便每天只有几 KB 的数据，列存格式和分区投影也能让方案在数据量、客户端类型、账号数扩展时无需架构调整。
数据量较小、访问频率不高的分析场景适合完全 Serverless 化。本方案中除了用户邮箱订阅 Kiro 本身，没有引入任何常驻基础设施。S3 + Athena + Amazon Quick（可选 Lambda 定时触发 ETL）的组合让团队用量观测在日常使用下的月度成本控制在 1 USD 以内。
在 Amazon Quick 里保留两张独立 Dataset 而不是 JOIN。fact 表加长表在 BI 层做扁平化 JOIN，会让静态度量被展开行数放大，是这类「主表 + 维度长表」建模在可视化环节最容易踩的坑。

沿着这条链路搭好之后，AI 开发工具的使用情况就从一封月度账单变成了团队可观测、可治理的资产：谁在快速消耗额度、谁还没被激活、哪些模型正在被真正使用，都能在 Dashboard 上一眼看到，并作为额度分配与培训计划的依据。

➡️ 下一步行动：

相关产品：

Amazon Athena — 使用 SQL 在 S3 中查询数据
Amazon Quick — 人工智能助手，用于研究、业务洞察、自动化和无代码应用程序构建
Amazon S3 — 适用于 AI、分析和存档的几乎无限的安全对象存储
Amazon QuickSight — 高速业务分析服务
AWS Lambda — 无需服务器即可运行代码

相关文章：

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者

探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用

亚马逊AWS官方博客