Use CloudKit Console to monitor and optimize database activity

Highlight

CloudKit Console 在 WWDC 2024 新增了开发者通知、Telemetry 可视化分析、结构化日志查询和自定义告警四项能力，让开发者在不写代码的情况下定位和解决 CloudKit 使用问题。

核心内容

你的 App 用 CloudKit 同步数据到 iCloud，线上出了问题怎么办？过去只能翻 Xcode 日志，靠猜测定位原因。如果问题是某个平台的错误率突然飙升，或者某个用户的 Quota 超限触发了大量失败请求，靠本地日志很难发现。CloudKit Console 在 WWDC 2024 补上了这块短板，新增了四项可观测性能力：开发者通知、Telemetry 图表、日志查询、自定义告警。

开发者通知让你第一时间知道容器里发生了什么——schema 变更、数据库告警、promotion 操作，都会推送到 Console 通知铃铛和邮箱。Telemetry 把 App 对 CloudKit 的请求按 requests、errors、error rate、latency、bandwidth 五个维度可视化，支持按 platform、operation 分组，支持时间范围和过滤条件。Session 演示了一个典型场景：先在 Error Rate 图表发现 Apple Watch 端的错误率异常，再用 Group By operation 定位到具体是哪个操作出了问题，最后跳转到日志查看单次请求的完整数据，发现是单个用户触发了大量 Quota Exceeded 错误。自定义告警则让你基于 Telemetry 指标设定阈值，问题再次出现时自动通知。

详细内容

开发者通知（00:35）

Console 顶部的通知铃铛是通知入口。CloudKit 开发者通知覆盖以下事件类型：database alerts、schema changes、promotions、resets、authorization token status。点击通知会跳转到 Console 对应页面，比如点击 schema 变更通知会跳转到 Schema History 页面，该页面记录了团队对容器 schema 的所有历史变更（02:38）。

通知可以按容器粒度配置。在 Settings > Notifications 中，你可以选择接收哪些类型的通知，以及通过 Web 还是 Email 接收。启用 “Manage Containers” 后，只勾选相关容器，避免测试容器的通知干扰（02:57）。

Telemetry 可视化分析（04:06）

Telemetry 提供五个核心指标图表：

• Requests：请求总量
• Errors：错误总量
• Error Rate：错误率（错误数 / 总请求数的百分比）
• Latency：延迟
• Bandwidth：带宽

每个图表都支持 Group By（按 platform、operation 等维度分组）、时间范围筛选、查询条件过滤。Session 中的排查路径如下：

1. 收到 database alert 通知，点击进入 alert details 页面（04:34）
2. Group By 改为 platform，发现 Watch 端错误数异常偏高（05:13）
3. 切换到 Error Rate 图表，确认 Watch 的错误率远高于其他平台（05:41）
4. 在 query builder 中过滤 platform 为 Watch，再 Group By 改为 operation，定位具体出问题的操作（06:03）

Telemetry 查询的 URL 可以直接分享给团队成员，让每个人看到相同的分析视图（06:48）。Usage 页面还提供了活跃用户数、设备分布、records 与 assets 的存储占比等统计（06:55）。

日志查询（07:15）

Logs 页面可以查看 App 触发的每一次 CloudKit 操作的完整请求数据。从 Telemetry 页面点击 “Query in Logs” 按钮，所有过滤条件会自动带过来，不需要重新配置（07:39）。

日志支持 Table View 模式，可以自定义表格列。Session 中演示了添加 userId 列后，立刻发现是单个用户在触发大量 Quota Exceeded 错误（08:27）。展开单条日志可以查看该事件的完整请求数据。日志查询结果可以导出为 CSV 或 JSON 格式（08:54），也可以保存查询条件或通过 “Copy Log Link” 分享给团队。

自定义告警（09:26）

自定义告警支持对 Requests、Errors、Error Rate 三个指标设定阈值规则。创建流程：在 Telemetry 图表下方点击 “Create Alert” 按钮，打开告警创建对话框。对话框中会显示告警预览图表，高亮区域代表阈值范围——与高亮区域相交的时刻就是告警会被触发的时刻（10:15）。

告警的过滤条件会自动继承当前 Telemetry 查询的过滤条件，确保告警只针对你关心的问题。可以配置监控周期（如每小时），阈值默认基于容器的历史平均值，也可以手动调整（10:42）。告警创建后会在 Alerts 页面统一管理，支持启用、禁用和删除（12:27）。

Session 给出了两个告警应用场景：App 上架新平台时，对 errors 数量配置告警来跟踪上线质量；同步逻辑优化完成后，对同步操作数量设定基于平均值的阈值告警来检测回归（11:49）。

核心启发

• 做什么：为生产环境的 CloudKit 容器配置自定义告警。为什么值得做：线上问题往往是用户先发现、开发者后知道，告警能把响应时间从”用户投诉”缩短到”分钟级自动通知”。怎么开始：在 CloudKit Console 的 Telemetry 页面，选择 Error Rate 指标，按 platform 分组后点击 “Create Alert”，阈值设为容器历史平均值的 2-3 倍。

• 做什么：用 Telemetry + Logs 的组合替代翻 Xcode 日志的排查模式。为什么值得做：Xcode 日志只能看本地单设备的数据，Telemetry 能看到全量用户的聚合数据，Logs 能看到单次请求的完整上下文，两者配合可以快速定位是全局问题还是单用户问题。怎么开始：下次遇到 CloudKit 同步问题时，先打开 Console 的 Error Rate 图表，用 Group By platform 缩小范围，再用 “Query in Logs” 查看具体失败请求的详情。

• 做什么：把常用的 Telemetry 查询和日志查询保存为可分享链接，放入团队文档。为什么值得做：同一个问题不同人排查时往往会重新构建相同的查询条件，保存和分享查询可以消除重复劳动，也方便在 on-call 时快速上手。怎么开始：在 Telemetry 或 Logs 页面配置好过滤条件后，复制浏览器 URL 或点击 “Copy Log Link”，粘贴到团队的 Slack 频道或 Confluence 页面。

关联 Session

• What’s new in SwiftData — SwiftData 数据持久化框架的最新更新
• Create a custom data store with SwiftData — 用 SwiftData 构建自定义数据存储方案
• Break into the RealityKit debugger — 用 RealityKit 调试器检查空间应用的实体层级
• Run, Break, Inspect: Explore effective debugging in LLDB — LLDB 调试实战技巧与高效断点策略
• What’s new in Xcode 16 — Xcode 16 开发者工具新特性概览