> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 审计、分析与错误

用工作区上下文与脱敏的事件数据理解活动。

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

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

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

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

[检查应用程序运行状况和操作设置](https://supastack.dev/zh/docs/web/security.md)

[诊断本地终端错误](https://supastack.dev/zh/docs/web/troubleshooting.md)


## 保留工作区审计轨迹

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

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


## 采集产品事件

可观测性包暴露 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，其中包含环境和服务基础字段；共享编辑层在发出任何行之前剥离秘密。


## 下一篇

[部署清单](https://supastack.dev/zh/docs/web/deployment.md)