Use CloudKit Console to monitor and optimize database activity
App Services 进阶 20m

用 CloudKit Console 监控和优化数据库活动

Use CloudKit Console to monitor and optimize database activity

2024年6月10日

在 Apple 官方观看视频

一句话判断

如果你的 App 用了 CloudKit 但从未打开过 Console 的 Telemetry 页面，你大概率遗漏了线上错误率和延迟的系统性问题——这场 Session 教你用对工具。

这场 Session 讲了什么

CloudKit Console 在 WWDC 2024 迎来了一次重大更新，新增了开发者通知、Telemetry 可视化分析、结构化日志查询和自定义告警四项核心能力。这些功能的目标是让 CloudKit 开发者能在不写代码的情况下，快速定位和解决 App 中的 CloudKit 使用问题。

开发者通知是 Console 新增的推送系统，当容器中发生 schema 变更、数据库告警、promotion 操作等事件时，Console 会通过站内消息和邮件通知相关人员。通知可以按容器粒度配置，避免收到无关容器的干扰信息。

Telemetry 是这次更新的重头戏。它将 App 的 CloudKit 请求按 requests、errors、error rate、latency、bandwidth 五个维度可视化展示，支持按 platform、operation 等维度分组，还支持时间范围筛选和查询条件过滤。Session 演示了如何通过 Error Rate 图表发现 Apple Watch 端的异常错误率，再通过 Group By operation 定位具体出问题的操作类型。

日志查询则提供了更细粒度的诊断能力，可以查看单次 CloudKit 操作的完整请求数据，支持自定义表格列和高级过滤。自定义告警允许你基于 Telemetry 数据设定阈值规则，当指标超过阈值时自动通知。

值得深挖的点

Telemetry 的分层排查方法论

Session 演示了一个非常实用的排查流程，值得所有 CloudKit 开发者学习。首先看 Error Rate 而不是 Error 绝对数量。因为不同平台的请求量差异很大，iPhone 上的 100 个错误可能只是正常比例，而 Watch 上 50 个错误可能意味着严重问题。通过 Error Rate 按平台分组，一眼就能看出哪个平台的比例异常。

定位到问题平台后，用过滤器将该平台的数据单独提取出来，然后切换 Group By 为 operation 类型，这样就能知道具体哪个 API 操作导致了大量错误。Session 中最终发现是 Watch 端某个操作触发了 Quota Exceeded 错误。最后通过 Logs 进一步确认是单个用户触发了大量配额错误，说明 App 没有正确处理配额不足的场景。

这个从宏观到微观的排查路径——Error Rate -> Platform -> Operation -> Logs -> User ID——是一个可以复用的排查方法论。

Schema History 与团队协作

新增的 Schema History 页面记录了容器 schema 的所有变更历史，每次变更都附带详细的上下文信息。对于多人协作的团队来说，这个功能解决了之前 schema 变更不透明的问题。之前如果有人在 Console 里修改了 schema，其他人可能完全不知道，直到 App 出现兼容性问题。现在通过通知和 Schema History，schema 的变更变得可追溯了。

代码片段

场景一：配置 CloudKit Console 通知

在 Console 中配置通知的步骤：

  1. 点击右上角用户菜单 -> Settings -> Notifications
  2. 勾选需要的通知类型（Service Updates、Database Alerts 等）
  3. 选择通知渠道：Web（站内）或 Email
  4. 在 “Manage Containers” 中选择只接收特定容器的通知
# 通知类型包括：
# - Schema Changes：schema 被修改时通知
# - Database Alerts：数据库出现异常时通知
# - Promotions：schema 推送状态变更时通知
# - Resets：数据库重置时通知
# - Authorization Token Status：授权令牌状态变更时通知

# 坑点：邮件通知默认关闭，需要手动开启
# 建议至少开启 Database Alerts 的邮件通知
# 这样即使不在 Console 页面也能收到关键告警

场景二：使用 Telemetry 排查错误

# 排查步骤（在 CloudKit Console 中操作）：

# 1. 打开 Telemetry 页面，查看 Error Rate 图表
# 2. 点击 Group By -> Platform，按平台分组
# 3. 发现某个平台（如 Watch）Error Rate 异常高
# 4. 在查询过滤器中添加条件：Platform = Watch
# 5. 修改 Group By -> Operation，查看具体哪个操作出错
# 6. 点击 "Query in Logs" 跳转到日志页面
# 7. 在日志表格中添加 userId 列，查看是否是特定用户的问题

# 坑点：Telemetry 数据有时间延迟（约 15-30 分钟）
# 如果需要实时调试，建议配合 Xcode 的 CloudKit 日志使用
# 另外注意 Telemetry 页面的 URL 可以分享给团队成员
# 这在协作排查问题时非常有用

场景三：创建自定义告警

# 在 CloudKit Console 中创建自定义告警：

# 1. 导航到 Alerts 页面
# 2. 点击 "Create Alert"
# 3. 选择指标（如 Error Count、Error Rate）
# 4. 设置条件（如大于某个阈值）
# 5. 设置时间窗口（如最近 1 小时）
# 6. 配置通知方式（站内 / 邮件）

# 建议配置的告警规则：
# - Error Rate 超过 5% 时告警
# - 特定操作的错误数超过阈值时告警
# - Latency P99 超过可接受范围时告警

# 坑点：告警阈值不要设得太低
# 否则会收到大量噪音通知导致对告警脱敏
# 建议先观察一周的正常波动范围再设定阈值

最佳实践

  • 迁移建议：如果你的团队已经在使用 CloudKit Console，第一步应该是配置好通知偏好和自定义告警。这是零代码改动就能提升线上可观测性的方式。然后在下次遇到 CloudKit 问题时，用 Telemetry + Logs 的组合替代之前的”看 Xcode 日志猜问题”模式。
  • 团队协作：将 Telemetry 的查询 URL 分享到团队频道，让每个人都能看到相同的分析视图。Schema 变更通知也应该配置给所有相关开发者，避免 schema 演进过程中的信息不对称。
  • 告警策略：先用内置的 Database Alerts 覆盖基础场景，再根据 App 的具体使用模式添加自定义告警。Error Rate 比纯 Error Count 更有诊断价值。

还有什么值得关注

  • Usage 页面提供了 records vs assets 的存储比例、活跃用户数和设备分布，这些数据对容量规划很有参考价值
  • Logs 查询支持添加自定义列（如 userId），方便在不侵犯隐私的前提下做用户级问题排查
  • Telemetry 和 Logs 的过滤条件可以互相传递，从宏观到微观的排查路径非常丝滑
WWDC 2024