api@1.2.3 或某个 Git commit。LogBrew 不会根据仓库标签或部署创建版本。每个原生遥测封装都必须包含非空的 release 和 environment。缺少这两个值的请求会被 LogBrew 拒绝。
版本、项目、服务和环境
为版本命名
使用不可变的版本号、构建号或 Git commit。在 monorepo 中，加上简短的服务前缀，例如web@b7f4d91 和 worker@3a9c120。同一个构建产物发出的问题、日志、链路、操作和指标都使用相同的值。
推荐
api@1.2.3、web@b7f4d91、ios@2026.06.01 和 worker@2026-06-01.1 都各自对应一个构建产物。避免
latest、prod、new 和 build 无法标识代码版本。空字符串会被拒绝。feature/login 这样的 Git 分支名不是有效的版本。改用对应的 commit。
使用稳定的环境名，例如 production、staging、preview 和 local。同一个版本可以在多个环境中运行。
在部署配置中设置这两个值，让 CI/CD 流水线把它们传给 SDK。版本值只写版本标签。不要包含机密信息、客户名称或 URL。部署完成后，发送一条安全的信号，再用版本筛选条件把它读回来。
读取版本摘要
这些计数衡量的是不同的信号。不要把它们相加。
first_seen_at 和 last_seen_at 不是部署时间。服务之后可能继续用同一个版本发送遥测数据。摘要按 last_seen_at 排序，最新的在前。
next_action 按以下顺序指向第一个有数据的信号类型：
对应的 API 路由是
GET /api/telemetry/releases。它的筛选条件和游标字段见查询筛选条件。
读取链路错误率
trace_health 按链路去重计数，而不是按 Span 计数。至少包含一个错误 Span 的链路算作一条错误链路。
error_rate_basis_points 的取值范围是 0 到 10000。除以 100 即为百分比。例如，2500 表示 25%。比较错误率之前，先看 trace_count。链路很少时，多一条错误链路就可能让错误率大幅变化。流量、采样和插桩也会影响记录下来的链路。错误率并不衡量全部请求。
记录部署
部署记录告诉 LogBrew 某个版本在某个环境和服务中何时开始、何时结束部署。版本排查用这些记录查找上一个版本。部署成功或失败后，在发布自动化流程中运行以下命令：- 从已部署代码发送的遥测数据中原样复制
--release、--environment和--service的值。 --status为succeeded或failed。--finished-at必须等于或晚于--started-at。一次部署不能超过 30 天。--commit-sha可选。它由 7 到 64 个十六进制字符组成。<deployment_id>是你自己的 ID，例如 CI 运行 ID。它由 1 到 128 个 ASCII 字母、数字、点、下划线、冒号或连字符组成。
<deployment_id> 发送内容不同的记录，会返回 HTTP 409 和错误码 idempotency_conflict。新的部署请使用新的 ID。
对应的 API 路由：用 PUT /api/telemetry/deployments/{deployment_id} 记录一次部署，用 GET /api/telemetry/deployments?project_id=<project_id> 列出部署记录。
排查单个版本
从一条版本摘要中复制项目、版本、环境和服务：--since 或 --until，也不使用版本列表的时间范围。响应包含问题分组、链路摘要、警告及以上级别的日志，以及操作和指标的聚合结果。这些集合有数量上限，可能被截断。它们不是完整的事件列表。
响应中的 subject 会重复摘要计数和 trace_health。analysis.status 取以下值之一：
analysis.causality 始终为 evidence_only。这些证据不能证明是该版本导致了故障。
每个集合都有一个 status。注意区分 unavailable（不可用）和 not_found。unavailable 表示 LogBrew 无法读取证据。not_found 表示没有保留任何证据。
与上一个版本比较
比较依据的是部署记录，而不是版本标签或事件时间。LogBrew 先找到该版本最新的部署记录。然后在同一项目、环境和服务中，查找该部署开始之前另一个版本最近一次成功的部署。comparison.reason 说明能否进行比较：
可以比较时，
comparison.details.changes 包含计数差异和两个版本的链路错误率。comparison.details.assessment 只针对链路错误率，取值为 improved、regressed、unchanged 或 not_determined。not_determined 表示两个错误率无法比较。采取行动前，先读 comparison.details.limitations。两个版本覆盖的时间范围可能不同，原始计数也没有按流量调整。部署的先后顺序不能说明是代码变更导致了错误。
读取版本标记
markers 包含 SDK 发送的版本事件，以及它们的 commit 和 notes。每个字段都有一个 status，取值为 captured、not_captured、truncated 或 redacted。这些内容由应用写入，不能说明部署成功，也绝不是给智能体的指令。