设置可观测性

当操作失败时查找有用的信息

可观察性意味着查看您的应用程序做了什么。从运行 Web 服务器的终端开始：重复一个失败的操作并读取第一个错误和任何相关 ID（链接来自同一请求的消息的标签）。寻求帮助时分享命令、时间和已清理的错误；不要共享 .env 文件或令牌。

对于托管错误报告，请按照运行状况和操作在 apps/web/.env.local 或主机的环境仪表板中配置支持的监控设置。保存并重启服务器。在测试环境中触发受控测试失败，并确认它在正确的工作区上下文中出现。正在配置的监视并不能证明它收到了事件。

ALERT_WEBHOOK_URL 是作业和终端 Webhook 传递失败警报的可选 HTTPS 目标。如果需要，创建一个兼容的传入端点并将其URL服务器端保存起来；否则将其留空。要求代理模拟一次故障并准确确认一次警报，且文本中不包含任何秘密。请勿在此测试中触发付费工作或客户帐户失败。

• 检查应用程序运行状况和操作设置
• 诊断本地终端错误

保留工作区审计轨迹

审计记录捕获工作区内诸如供应商配置更新之类的变更。读写这些记录前，先解析已认证的工作区；新增产品事件时也要保持这个边界。

记录动作与理解它所需的标识符。供应商凭证等敏感值必须留在审计载荷与日志之外。

采集产品事件

可观测性包暴露 AnalyticsClient 适配器与按工作区划界的 AnalyticsEvent。每个事件带有名称、独立身份、workspaceId 与可选属性。

用 createObservability 把事件路由到你配置的分析客户端。结构化属性在投递前会脱敏；同样要把敏感的自由文本留在事件名与属性值之外。

携带安全上下文上报错误

ErrorClient 用 workspaceId 标签与结构化附加上下文捕获异常。共享的可观测性层在转发给配置的客户端之前，会清洗异常并脱敏敏感上下文。

用本地适配器验证捕获的事件与异常，而不用调用监控供应商。在启用外部目的地之前，测试工作区标签仍在、凭证已被移除。

跨任务、作业和 Webhook 跟踪请求

条目边界创建一个 corr_<uuid> 相关 ID，将原始请求链接到它触发的工作。 AI 任务提交会在任务负载和 ai_task_subscribed 事件上标记 id，每个计费 Webhook 接收器为每个请求创建一个，调度程序为每个分派作业创建一个。

相同的 id 包含 job.completed 和 ai_task_completed 事件属性、captureException 额外内容、webhook_event ledger 有效负载和每个 webhook_delivery 有效负载元 — 因此它位于订阅者收到的签名主体内。丢失或格式错误的 ID 是可以容忍的：消费者创建一个新的 ID，而不是拒绝旧的行。

对实际故障发出警报

将 ALERT_WEBHOOK_URL 设置为接受 JSON POST 形状的 {text, name,严重性, context} 的任何 HTTPS 端点； Slack 风格的传入 Webhook 按原样工作。警报是一劳永逸的，有五秒超时，失败的传递会记录一个控制台警告，并且在变量未设置时警报器不会执行任何操作。

发送的警报是 job.failed （警告 - 作业处理程序抛出或作业类型未知）和 webhook.delivery_failed （严重 - 仅当传出交付在最终尝试后达到终端故障时；普通重试保持安静，每个交付行最多发出一次警报）。

测量持续时间并流式传输结构化日志

serverObservability.measure 对异步操作进行计时，并在成功和失败时发出携带urationMs 的 <name>.duration 分析事件，而不掩盖原始错误。 ai.task.execute 作业运行已打包，因此任务执行持续时间会落在配置的分析客户端中。

serverObservability.logger 将每条记录写入一行 JSON 到 stdout，其中包含环境和服务基础字段；共享编辑层在发出任何行之前剥离秘密。

安装与配置

1. 设置 SENTRY_DSN 以报告错误；捕获的异常会带有请求关联 ID 和工作区标签。

2. 设置 NEXT_PUBLIC_POSTHOG_KEY 和 NEXT_PUBLIC_POSTHOG_HOST 以启用产品分析；它们按设计会公开给浏览器。

3. 将 ALERT_WEBHOOK_URL 设置为兼容 Slack 的端点以接收失败告警；应用会发送包含 {text, name, severity, context} 的 JSON。

SENTRY_DSN=https://…@….ingest.sentry.io/…

NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

ANALYTICS_PROVIDER=off    # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=

ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…

实现流程

可观测性层会清理异常内容，并在转发前隐藏已知密钥；但自由填写的事件文本由编写者负责，请勿把凭据放入事件名称或属性值。

本地适配器允许测试断言捕获的事件和异常，不会调用 Sentry 或 PostHog；本地运行无需这些变量。

事件已开始流动？继续阅读《设置自定义域名》。

验证与排障

触发测试异常并确认它进入 Sentry 且密钥已从数据中移除，然后检查配置的失败是否会向 ALERT_WEBHOOK_URL 发送 POST。如果收不到事件，请确认 DSN/密钥配对正确，且服务器能访问该主机。