flutter-observability

Flutter 可观测性

在不收集不必要用户数据的前提下，让生产环境故障可诊断。除非用户要求迁移，否则应保留现有的 Sentry、Crashlytics、OpenTelemetry、Dynatrace、Datadog 或其他遥测技术栈。

前置检查

在诊断原因或提出变更建议前，先阅读 SDK 限制、入口点、flavor/环境，以及完整的现有遥测和交付接线配置：SDK 初始化、错误钩子、同意/隐私规则、网络和导航埋点、isolate 用法、混淆、符号保留/上传、CI 和发布标识。不要仅凭仪表板上的症状推断根因。如果无法获取代码仓库或后端证据，首先列出仍需提供的确切制品和后端证据，说明诊断尚未完成，并让任何修复建议保持有条件。应从具体的诊断问题或事件入手；默认不要为每个事件都添加埋点。

定义一个精简的运维事件约定：稳定的事件名称、严重级别、时间戳、发布版本/构建版本、环境、平台、关联标识、结果、有意义时的耗时，以及数量有限且已脱敏的属性。不要将用户内容、令牌、凭据、支付数据以及原始请求/响应正文纳入遥测数据。

每个埋点方案都必须明确涵盖全部五项治理控制：脱敏、同意、采样、后端保留/访问，以及有界离线缓冲。说明哪些控制由客户端代码负责，哪些必须在后端验证；不要暗示仅靠客户端配置就能强制保留期限或访问控制。

路由工作

• 对于框架、根 isolate、子 isolate 和异步错误覆盖范围，请阅读错误和崩溃捕获。
• 对于结构化日志、面包屑、追踪、关联、采样、脱敏和同意，请阅读日志、追踪和隐私。
• 对于供应商选择或保留、发布元数据、符号、缓冲和端到端验证，请阅读供应商和验证。

只加载与请求相关的参考资料。

边界

• flutter-performance 负责 profile 模式下的测量和优化决策；生产追踪可以发现回归或潜在瓶颈，但不能作为优化已奏效的证据。
• flutter-product-analytics 负责漏斗、归因、转化、实验和业务事件；运维遥测用于回答可靠性和事件诊断问题。为用户旅程添加埋点时，应说明这一区别，以免分析事件或 UI 跟踪泄漏到运维事件约定中。
• flutter-networking 负责 HTTP 行为；此技能定义围绕网络行为的安全关联和结果信号。
• flutter-security 负责全面的安全审查；此技能要求尽量减少遥测数据、进行脱敏、征得同意、留意数据保留，并遵循最小暴露原则。
• flutter-build-release 负责制品和符号生成；此技能负责验证发布版本/构建版本标识及符号上传关联。

验证

测试规范化、脱敏、采样、同意、关联和适配器行为。在非生产后端/环境中，触发一个已处理错误以及每种所需的受控未处理错误类别，然后确认数据仅被采集一次、发布版本/构建版本/环境正确、堆栈可供符号化处理，并且实际仪表板或查询界面中显示的属性安全。确认其中不包含机密和不允许收集的个人数据。验证遥测离线、遭遇速率限制或不可用时的降级行为。

不要因为初始化代码编译通过就声称可观测性已生效。应说明哪些信号已完成端到端验证、哪些仅经过单元测试，以及仍有哪些事项受供应商或设备条件限制。

来源

• Flutter 中的错误处理
• PlatformDispatcher.onError
• Dart 开发者日志