For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/modules/observability.md (or send Accept: text/markdown).
审计、分析与错误
用工作区上下文与脱敏的事件数据理解活动。
当操作失败时查找有用的信息
可观察性意味着查看您的应用程序做了什么。从运行 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，其中包含环境和服务基础字段；共享编辑层在发出任何行之前剥离秘密。