可观测性

生产遥测运行在三条腿上：Sentry 用于错误，OpenTelemetry 跟踪用于热路径， Horizon 用于队列健康。 管理员 Site Health 药丸（参见 Site health & failed jobs）一目了然地总结它们。

Sentry

设置 SENTRY_DSN，应用程序中未处理的异常会流入 Sentry， 带有堆栈跟踪、请求上下文和用户/工作区元数据。 面包屑轨迹捕获每个错误的最后 100 行日志。 通过 sentry-laravel 集成。

Sentry 中有用的过滤器：

• 标签 workspace_id 将错误范围限定到租户。
• 标签 agent_id 当错误源自小部件请求时。
• 发布标签匹配部署提交 SHA — 当出现回归时易于二分查找。

OpenTelemetry 跟踪

OTEL 导出器将跟踪发送到 OTEL_EXPORTER_OTLP_ENDPOINT — 通常是 Honeycomb 或 Grafana Cloud Tempo。Span 包装热路径：

• widget.message.receive — 传入 HTTP、验证、JWT 验证。
• rag.curated.match — 短路检查。
• rag.embed — 查询嵌入调用。
• rag.vector.search — ANN 搜索。
• rag.rerank — 交叉编码器。
• rag.prompt.assemble — 本地 CPU 工作。
• rag.llm.first_token — 首个 token 时间（标题指标）。
• rag.llm.stream — 完整流持续时间。
• rag.persist.async — 流后保存。

每个 span 都标记有 workspace_id、agent_id、conversation_id、 provider（cloudflare / openai）和任何缓存命中标志。 重要的是 rag.llm.first_token 的 p95 — 那是您的热路径 SLO。

Horizon

/horizon 是队列仪表板。生产环境必需 — 没有它，您对积压情况视而不见。观察：

• Wait time — 作业在被拾取之前坐了多久。健康是 < 1s；调查 > 10s。
• Throughput — 按队列的作业/分钟。
• Failed jobs — 落入 failed_jobs 的任何内容也显示在这里。

要监视的队列：

队列	上面有什么
default	杂项：使用事件、间隙检测、审计日志、webhook 交付。
crawl	CrawlSourceJob、CrawlPageJob、IngestNotionPageJob、IngestGoogleDocJob。往往是队列深度最长的。
index	IndexDocumentJob、IndexTextSourceJob。嵌入繁重。

日志

标准 Laravel 日志记录。默认通道：

• stdout — 由 Laravel Cloud / Docker 捕获。
• sentry — 错误级别及以上。
• slack — 关键级别，发布到 ops 通道。

使用 php artisan pail 在本地跟踪日志。

健康端点

GET /up 是就绪探针 — 如果应用程序启动，返回 200 和小 JSON 主体。 将其用于负载均衡器健康检查。 对于更深入的检查，App\Support\PlatformAdminHeader 运行多步健康检查，并通过 Inertia 共享属性在每个管理员页面上公开结果。

要监视的指标

最重要的少数指标：

• p95 first-token latency — < 1s。
• p95 full-response latency — 短答案 < 5s。
• Crawl queue depth — 应在几分钟内排空。
• Index queue depth — 应在几分钟内排空。
• Failed-jobs count — 稳态下为 0。任何 > 50 都值得警报。
• LLM provider error rate — < 流的 1%。
• Vector store query latency — p95 < 100ms。

警报

推荐的 PagerDuty / Slack 警报：

• Sentry — 新的发布阻止错误。
• Honeycomb — first-token p95 > 1.5s 持续 5 分钟。
• Horizon — failed-jobs delta > 5 分钟内 10。
• Stripe webhook — > 5 次连续验证失败（签名密钥不匹配）。
• Reverb — 进程关闭。

Site Health 药丸

管理面板中的标题药丸是快速视觉检查，确保一切配置正确。 绿色是稳态；如果变为琥珀色，下拉列表告诉您哪个检查失败并链接到设置页面进行修复。 参见 Site health & failed jobs。