读取响应
按以下顺序读取每个响应：- 读取 HTTP 状态。
- 确认响应体符合该路由规定的结构。
- 确认每个
project_id都在请求的项目范围内。 - 保持规范枚举值和标识符不变。
- 只有客户端支持
next_action的code和target时，才执行它。 - 把
null、省略的字段和空列表当作 3 种不同的状态。
200 OK 可以包含空列表。空的日志列表表示没有日志匹配该请求，不表示问题、链路或操作也为空。不要因为时间戳相近就关联信号。只有响应包含准确的 trace_id 时，才沿该链路继续读取。
404 和空列表是不同的结果。没有记录匹配时，列表路由返回 []。找不到可读取的记录时，详情路由返回 404 和 code: not_found。这两种结果都不能证明数据接收失败。
应发送的数据
你发送的遥测数据决定了响应的价值。在每个封装或每次 SDK 配置中发送以下值：release和environment。- 服务、操作和指标的稳定名称。
- 日志、Span（一次计时操作）、操作和问题属于同一请求时，发送链路上下文。
- 规范的严重程度值：
info、warning、error和critical。 - 有助于调试的属性，但不要包含机密信息或不必要的个人信息。
数据接收响应
公开 SDK 会替你读取POST /v1/events 的响应。应用代码无需处理它。
SDK 批次响应
SDK 批次成功时返回200 OK，并给出每个数据流已接收的数量：
这些数量只涵盖该批次。重试一个 LogBrew 已接收的批次时，每个数据流都返回
0，信号数会计入 already_accepted。重试时保留原始事件 ID。
原生封装响应
POST /api/telemetry/ingest 返回 200 OK，并给出每个数据流已接收的条目数：
metrics 或 context_updated 字段。不要添加它们。already_accepted 统计 id 已被 LogBrew 为该项目接收过的条目。请参阅直接发送原生封装。
数据接收错误
401 和 code: ingest_key_invalid 表示接入 Bearer 令牌已撤销、已过期，或对该项目无效。在 POST /v1/events 上，缺少 Bearer 令牌或令牌不是接入密钥时，返回 401 和 code: unauthorized。使用当前的项目级接入 Bearer 令牌。不要改用账号 Bearer 令牌重试。
被拒绝的 SDK 批次返回 422 和 code: validation_failed：
error 值包括 SDK event batch requires at least one event 和 SDK event type is not supported by this ingest route。检查 SDK 版本和传输配置。不要发送空批次。不要只为了通过验证而更改信号类型或 ID。
使用 POST 以外的方法时，请求返回 405 和 code: method_not_allowed。无法读取的 JSON 请求体返回 code: invalid_json。
遥测列表响应格式
列表路由默认返回不带外层对象的 JSON 数组。成功但为空的列表是[]。
使用 pagination=cursor 时，路由返回一个封装。集合键与信号对应：
next_cursor 是包含续读字段的对象，在最后一页为 null。各行按从新到旧排列。请参阅游标分页。
日志响应
使用limit=1 的日志游标分页：
level 和用于显示的 severity。两者都是规范值。triage 保存严重程度规则的结果。请参阅严重程度规则响应。
日志没有关联链路时，trace_id 和 span_id 为 null。此时 next_action 为 inspect_related_logs，目标为 telemetry_logs。日志、问题和操作使用同样的 2 组 next_action 值。
GET /api/logs/{log_id} 以相同结构返回 1 条日志。
问题响应
GET /api/telemetry/issues/{issue_id} 返回 1 个分组问题。列表返回同样的对象。本示例使用默认的响应版本 1：
status 为 unresolved、resolved 或 ignored。已归档的问题的 triage.ignored 为 true。next_action 的各组值及其后续读取，请参阅排查问题。
first_seen_at 和 last_seen_at 分别是首次和最近一次发生记录的时间。状态变化时，它们不会改变。
有些字段只在 LogBrew 有相应数据时出现：
symbolication.status 为 resolved、invalid_metadata、artifact_not_found、source_not_resolved 或 unavailable。列表、状态更改和规则更改都不返回 symbolication。
使用 response_version=2 时，问题包含相同的字段，并有以下变化：
error 和 critical 为 high，warning 为 medium，info 为 low。推导基于 triage.effective_severity，所以问题的严重程度规则可以改变它。
使用 response_version=3 时，问题包含版本 2 的全部字段，外加 assignee。问题没有负责人时，assignee 为 null：
被分配的成员无法再读取该项目时，问题不显示负责人。
使用
response_version=4 时，assignee 还带有 type。user 类型的负责人与版本 3 一样，有 user_id、name 和 email。team 类型的负责人有 team_id、slug 和 name。版本 3 把团队负责人显示为 null。CLI 请求的是版本 4：
response_version 都返回 422 和 code: validation_failed。在一页游标结果中，issues 里的每个问题都使用同一版本。
负责人列表响应
GET /api/telemetry/issues/assignees?project_id=<project_id> 返回该项目中所有可被分配问题的账号：
response_version=2 还可以获取 teams：该项目所在组织的每个团队，包含 team_id、slug 和 name。
如果账号无法读取该项目，路由返回 404 和 code: not_found。
操作响应
distinct_id 跟随 1 个操作者或会话。把 distinct_id 和 session_id 当作不透明标识符。session_id 和 trace_id 缺失时为 null。span_id 缺失时会被省略。操作没有严重程度。请参阅产品事件采集。
指标响应
unit、temporality、trace_id 和 span_id 缺失时为 null。null 值不等于零。
版本响应
trace_health.status 的值为 unknown（该行没有链路）、no_errors_observed 或 errors_observed。error_rate_basis_points 是含有错误 Span 的链路所占的比例，取值从 0 到 10000。它不是所有请求的错误率。
next_action 按以下顺序指向第一个有数据的信号类型：
请参阅版本。
链路发现响应
GET /api/telemetry/traces?pagination=cursor 为每条链路返回 1 行，并为返回的这一页附上 naming_quality 回执：
naming_quality 只涵盖返回的这一页，不是整个账号的评分。truncated: true 表示还有下一页。当这一页里有通用名称、未匹配的路由或通用操作名时，next_action 为 improve_trace_naming，目标为 sdk_configuration。不使用 pagination=cursor 时，路由返回不带外层对象的链路数组，且没有 naming_quality。
next_cursor 包含 time 和 trace_id。把它们作为 cursor_time 和 cursor_trace_id 发送。
GET /api/telemetry/traces/{trace_id} 返回 1 条链路的所有 Span。GET /api/telemetry/traces/{trace_id}/summary 返回根 Span、错误 Span、服务、耗时和最慢路径，不含原始 Span 属性。摘要返回 404 表示没有链路匹配完整的范围。不要去掉筛选条件后重试。请参阅链路 Span 与摘要响应。
空列表与缺失的记录
列表读取可能没有匹配结果。详情读取遵循不同的约定：
缺失的日志返回以下
404：
"error": "issue not found"。缺失的链路摘要使用 "error": "trace not found"。未知的 ID 和账号无法读取的 ID 返回相同的响应。
如果列表只指定了 1 个 project_id，而账号无法读取该项目，会返回 200 和空列表。报告“没有数据”之前，先检查项目 ID。
被拒绝的项目选择
日志、问题、操作、指标、版本和链路列表接受用project_id 指定 1 个项目，或用 project_ids 指定 2 到 50 个项目。日志属性目录接受同样的选择参数。问题发生记录历史不接受这些参数。
同时包含 project_id 和 project_ids 的请求返回 422：
project_ids 包含无效的 UUID、重复的 ID，或 ID 少于 2 个、多于 50 个，也会返回 422 和 code: validation_failed。
如果账号无法读取 project_ids 中的某个项目，整个请求都返回 404，不会把其他项目作为部分结果返回：
403 和 code: forbidden。请参阅项目范围。
游标错误
日志、问题、操作、指标和问题发生记录使用cursor_time 和 cursor_id。被拒绝的游标返回 422 和 code: validation_failed。这些错误不表示列表为空。
例如：
next_cursor。不要用当前时间替换 cursor_time。如果丢失了游标，用 pagination=cursor 和原始筛选条件从头开始。未知的查询键或类型错误的值返回 422 和 "error": "invalid query parameters"。
版本游标响应
版本游标有 5 个字段。请求成功但没有匹配结果时返回200：
next_cursor 不为 null 时，在下一个请求中发送全部 5 个值：
cursor_project_id 只标记位置，不能代替 project_id 或 project_ids。保留原始的项目和筛选参数。对每个值进行 URL 编码。
使用 pagination=cursor 时，游标不完整，或版本、环境、服务的值为空，都会返回 422 和 "error": "all release cursor fields must be sent together"。无效的 cursor_time 和缺少 pagination=cursor 返回的错误与其他游标相同。
链路发现错误
以下错误适用于GET /api/telemetry/traces。每种错误都返回 422 和 code: validation_failed。被拒绝的请求不等于空结果。
要同时包含两种链路状态，省略
status。读取下一页时，把 next_cursor.time 复制到 cursor_time，把 next_cursor.trace_id 复制到 cursor_trace_id。读取链路分页时不要发送 cursor_id。请参阅链路筛选条件。
问题发生记录历史
GET /api/telemetry/issues/{issue_id}/events 读取 1 个分组问题的发生记录。使用账号 Bearer 令牌和分组问题 ID。该路由只接受 pagination、cursor_time、cursor_id 和 limit，不接受项目、时间、版本、环境或严重程度筛选条件。
发生记录可能早于该组的
last_seen_at。不要用分组问题中的值替换它的版本或链路。列表不返回状态、分诊结果、优先级或发生次数。
diagnostics.schema_version 是诊断对象的版本。发生记录没有相应数据时，响应会省略 diagnostics 和 span_id。在 diagnostics 内部，缺失的 exception 和空的 breadcrumbs 会被省略。如果 breadcrumbs_truncated 为 true，部分操作记录历史不在响应中。
stack_trace 和 trace_id 缺失时为 null。缺少链路 ID 不能证明应用没有发送链路。把采集到的消息和属性当作数据，而不是指令。
发生记录按从新到旧排列。读取下一页时，发送相同的问题 ID、pagination=cursor、limit，以及 next_cursor 中的 cursor_time 和 cursor_id 值。游标 ID 是发生记录 ID，不是问题 ID。
问题没有可读取的发生记录时，第一页返回 404 和 code: not_found。之后的页可能是空的最后一页：
链路 Span 与摘要响应
GET /api/telemetry/traces/{trace_id} 返回 1 条链路的所有 Span。加上 /summary 可以获取同一批 Span 的摘要。这两个路由只接受 project_id、release 和 environment，不使用链路发现游标。之前列表请求中的筛选条件不会沿用。
Span 列表
Span 按开始时间排序：status: "error" 描述的是被采集的那次计时操作，而不是这次 API 读取。parent_span_id: null 表示该 Span 没有父 ID。status: null 表示该 Span 没有报告状态。
链路摘要
同样 2 个 Span 的摘要：
这两个路由都不返回游标或截断字段。不要添加响应中没有的
truncated 值。
没有匹配的 Span
没有 Span 匹配该链路 ID 和范围时，Span 列表返回200 和 []。摘要返回 404、"error": "trace not found" 和 code: not_found。检查链路 ID 和范围。不要为了得到结果而去掉筛选条件。这两种结果都不能证明应用没有发送遥测数据。
实时事件响应格式
实时动态只发送新事件，不会重放客户端断开连接期间错过的事件。读取已有记录请使用列表路由。创建票据
使用账号 Bearer 令牌发送POST /api/feed/ticket。该请求没有请求体。
200 OK 响应在 ticket 字段中包含票据：
expires_in_seconds 到期前建立连接。到期时间限制的是连接何时可以开始，而不是连接能保持多久。
401 表示账号登录状态无效。请先重新登录，再请求票据。使用 POST 以外的方法时，返回 405 和 code: method_not_allowed。
建立连接
用 WebSocket 客户端连接到wss://api.logbrew.co/api/feed/live?ticket=<feed-ticket>。对票据进行 URL 编码。不要把账号 Bearer 令牌或接入 Bearer 令牌放进 URL。401 表示票据或账号登录状态无效。重新登录后，创建新的票据。
出错后先等待，再重新连接。不要在紧凑的循环中反复重连。
读取消息
每条消息都是{ "type": "...", "data": ... } 封装。先读取 type，再解析 data。跳过客户端不支持的类型。
native_issue 事件使用问题响应版本 1：已归档的问题显示为 ignored，事件中没有优先级。指标和版本不是实时事件类型，请用各自的列表路由读取。票据不选择项目。在项目视图中显示每个事件之前，先检查它的 project_id。logbrew watch --json 使用的就是这个实时动态。请参阅 CLI 参考。
处理已关闭的连接
其他断开连接的情况可能没有 LogBrew 给出的原因。重新连接后，再次读取列表路由，并按 ID 匹配记录。
问题状态响应示例
使用{ "status": "resolved" } 调用 PATCH /api/telemetry/issues/{issue_id} 会返回 200 OK 和更新后的分组问题，结构与问题响应相同。查询键 response_version 用于选择版本。该请求不返回表示成功的标志。
请求体设置 status、priority 和 assignee 中的 1 个或多个。status 接受 unresolved、resolved 或 archived。ignored 是 archived 的旧名称。请参阅更新单个问题。
显示成功之前，先检查返回的 id、status 和 priority。不要根据提交的值拼出结果。状态更改不会删除发生记录，也不会改变 first_seen_at 和 last_seen_at。它不会改变 severity 或严重程度规则。
被拒绝的更改返回 422 和 code: validation_failed：
已经是所请求值的字段不会变化。超时或响应丢失后，重新发送同一个请求，或先读取该问题。读取当前状态之前，不要发送不同的更改。请参阅写入请求。
POST /api/telemetry/issues/bulk 返回 200 OK，按请求顺序为每个请求的问题 ID 给出 1 个结果。找到的每个问题都使用版本 3 的结构。not_found 结果包含 issue: null：
outcome 为 updated、unchanged 或 not_found。重复的请求返回 unchanged，不做任何更改。请参阅批量更新问题。
在以下情况下，整个批量请求都会失败：
分析请求范围
分析路由、指标序列路由和信号数量路由读取 1 个项目和 1 个时间范围。每个请求都需要project_id 和 since。since 接受 24h 或 7d 这样的简写时长，或 RFC3339 时间戳。until 接受 RFC3339 时间戳，默认为请求时间。时间范围包含 since，不包含 until，且不能超过 31 天。
service_name、release 和 environment 是可选的精确筛选条件。LogBrew 去掉首尾空格后，每个值必须为 1 到 256 个字符。分群对比路由把这些筛选条件放在每个分群内部，而不是顶层。
如果账号无法读取该项目，这些路由返回 200 OK 和零计数，不会返回 404。空结果不能确认项目访问权限。把 project_id 与该账号可读取的项目进行比较。通过不包含该项目的 MCP 授权发出的请求返回 403 和 forbidden。
每个响应都以
schema_version、query 和 purpose 开头。query 回显实际生效的范围，省略你没有发送的筛选条件。purpose 是纯文本，说明该路由回答什么问题。
分母为零时，比率会被省略。省略的比率既不是 0，也不是 null。信任某个比率之前，先读取 coverage。
以下错误使用 HTTP
422 和 validation_failed：
例如，不带
project_id 的请求返回：
error 文本。下文对应的小节列出了这些错误。
未知的查询键返回 422 和无效的查询参数响应。未知的 JSON 字段、缺少必填的 JSON 字段或不支持的枚举值返回 invalid_json。请参阅无效的 JSON。使用错误 HTTP 方法的请求返回 405 和 method_not_allowed，其 next 文本会指出受支持的方法和字段。请参阅不支持的方法。
产品分析概览响应
GET /api/telemetry/analytics/overview 显示 1 个项目中的活动：操作量、用户、会话、时间序列、热门操作，以及已分类的页面浏览、屏幕浏览和互动。用它查找其他分析路由所需的准确事件名称。
发送 response_version=3。版本 1 和 2 返回相同的计数，但 estimation.method 使用旧的标记值。版本 1 统计已识别用户时不检查主体类型。版本 2 和 3 只统计类型为 user 的主体，并增加了匿名主体计数和 subject_coverage。
以下请求以 5 分钟为时间桶读取 1 小时的数据，每个热门列表返回 2 行：
概览成功响应
在这个模拟结果中，项目的 120 个操作分布在 12 个时间桶中的 2 个里。其中 20 个操作来自匿名主体。每个操作都有会话 ID。一半的操作有链路 ID。解读概览
5 个subject_coverage 计数相加等于所在部分的事件总数。只有 identified_user_events 计入用户。anonymous_actions 等于 summary.actions 减去 identified_actions。
series 只包含有活动的时间桶。expected_buckets 是该时间范围内可能的时间桶数。除非图表注明了这条规则，否则不要把缺失的时间桶画成实测的零。时间桶按 UTC 时间间隔边界对齐。如果时间范围从某个时间桶中间开始，结果会包含这个不完整的时间桶。
classified_activity 统计页面浏览、屏幕浏览和互动。屏幕浏览和互动同时也是操作，页面浏览不是。不要把 summary.actions 加到 classified_activity.summary.events 上。
把 classified_activity.top_events 中的 kind 和 event_name 复制到漏斗步骤、留存选择器、生命周期选择器、路径锚点和分群目标中。top_events_truncated 为 true 表示还有出现次数更少的名称未列出。把 top_limit 调高（最多 20）可以看到更多。
analysis_level 为 no_data、event_only、user_level 或 user_and_session。如果项目没有操作，也没有已分类的事件，next_action.code 为 capture_product_activity。请参阅产品分析。
概览错误
除通用范围错误外，概览在遇到以下值时返回422 和 validation_failed：
interval 默认为 auto，会选择所需时间桶不超过 300 个的最小间隔。top_limit 默认为 10。
有序漏斗响应
POST /api/telemetry/analytics/funnel 衡量 2 到 8 个步骤的按顺序完成情况。从概览的 classified_activity.top_events 中复制每个准确的 kind 和 event_name。名称相似的操作不算匹配。以下请求体统计先浏览 /pricing、然后在 1 小时内完成注册的会话：
analysis_unit 为 session 或 identified_user，默认为 session。步骤的 kind 为 page_view、screen_view 或 interaction。漏斗路由不接受 response_version。
漏斗成功响应
200 OK 响应：
coverage。selected_unit_coverage_rate 是 LogBrew 能够使用的所选步骤事件所占的比例。响应不返回原始身份信息。请参阅产品分析。
解读转化率和覆盖率
entry_rate 等于 entered_units 除以 candidate_units：60 个中有 50 个。overall_conversion_rate 等于 completed_units 除以 entered_units：50 个中有 15 个，即 30%。它不是 15 除以所有候选单位。这些计数无法说明单位为什么中途流失。
覆盖率统计的是事件，不是会话。这里有 120 个事件匹配某个步骤，其中 20 个没有会话 ID。结果在会话计数中排除了这 20 个事件。不要把它们当作 20 个失败的会话。
第一个步骤没有 conversion_from_previous。最后一个步骤没有 drop_off_to_next_units，也没有 drop_off_to_next_rate。
只有各步骤的时间严格递增时，单位才会到达后面的步骤。时间戳相同的事件不能同时满足两个相邻步骤。最后一个步骤必须在第一个步骤之后的 conversion_window_seconds 内发生。
会话模式统计的是会话，不是人。只有事件带有类型为 user 的不透明主体 ID 时，才使用 identified_user。该模式可以把转化窗口内不同会话中的事件关联起来。比较结果时，保持相同的单位和相同的步骤。
conversion_window_seconds 默认取 24 小时和时间范围长度中较短的一个。最大值是时间范围的长度，以整秒计，向上取整。
空漏斗结果
成功但为空的响应仍会列出所请求的步骤，其units 为零。如果没有候选单位，summary 会省略 entry_rate 和 overall_conversion_rate。路由不会因为没有事件匹配而返回 404。
读取 coverage 和 next_action 找出原因：
被拒绝的漏斗请求
除通用范围错误外，以下请求返回422 和 validation_failed。步骤少于 2 个或多于 8 个：
conversion_window_seconds 为 0，或大于时间范围的长度：
event_name 为空、超过 256 个字符或包含控制字符时，返回 product analytics funnel event_name must be non-empty, control-free, and at most 256 characters。interaction 步骤还必须是有效的操作名称，否则错误为 product analytics interaction event_name must be a bounded stable action name。
先修正请求，再重新发送。不要只为了得到非空结果而删除步骤或更改分析单位。
精确事件分析与自动分析
留存和生命周期接受两种请求结构。用response_version 选择能回答你问题的结构：
精确选择器包含
kind 和 event_name。kind 为 page_view、screen_view 或 interaction。从 classified_activity.top_events 复制 event_name。不要根据按钮文字猜测事件名称。
两种结构都只统计用户，即类型为 user 的不透明主体 ID。匿名主体和没有可用主体 ID 的事件不计为用户。响应从不返回主体 ID。
固定间隔为 hour、day、week 和 thirty_day，都是固定时长。thirty_day 是 30 天，不是日历月。如果省略 interval，时间范围不超过 48 小时时 API 使用 hour，更长时使用 day。
精确事件留存请求
把以下请求体发送到POST /api/telemetry/analytics/retention。它查询用户在时间范围内首次结账后是否会再次结账：
until。两个选择器可以是同一个事件。
精确事件留存成功响应
在这个模拟示例中，2 个用户完成了结账。第一个用户在 6 月 1 日 12:00 完成结账，13:00 再次结账。第二个用户在 6 月 2 日 12:00 完成结账。6 月 2 日 13:00，第二个用户浏览了一个页面，但没有再次结账。解读留存
覆盖率统计了全部 4 个已分类事件，但每个结账选择器只匹配其中 3 个。页面浏览不算回访。2 个用户中有 1 个再次结账，所以return_rate_after_start 为 0.5。
只有第一个用户在锚点之后有完整 1 天的观测时间。该用户在当天回访，所以曲线比率为 1.0。第二个用户只有 12 小时的观测时间，不符合周期 0 的条件，所以第二个群组的单元格省略了 retention_rate。不要把该用户算作流失。
weighted_retention_rate 用所有留存用户数除以所有符合条件的用户数。fully_observed_cohort_average_rate 是所有用户都符合条件的群组的比率的简单平均值。群组是从 since 开始的固定时间桶。cohorts 只包含有用户的群组。
使用 mode: "return_on_or_after" 时，曲线省略 window_end_seconds。
自动留存
发送response_version: 2，且不发送 start_event 或 return_event。每个受支持的页面浏览、屏幕浏览和互动都同时算作起始和回访。这个版本选择的是一组事件，而不是 SDK 的采集格式。
summary、curve、cohorts 和 next_action 结构与精确事件响应相同。以下摘录显示有变化的字段。在这个示例中，同样的 2 个用户有 3 个事件，没有页面浏览：
start_events 和 return_events 都等于 classified_events。这些计数是事件数，不是用户数。
没有符合条件用户的留存
成功的结果中可能没有群组用户。以下摘录显示 1 个没有群组的请求周期：coverage 和 next_action。它们能区分范围内没有已分类事件（capture_product_activity）和事件没有用户（identify_product_users 或 identify_returning_users）这两种情况。缺失的比率不是实测的零。
留存错误
除通用范围错误外，以下请求返回422 和 validation_failed：
单元格上限取决于时间范围和周期数，而不是用户数。30 天的时间范围配合
interval: "hour" 有 720 个群组时间桶。在 interval_count: 1 下就是 720 个单元格，超过 500：
精确事件生命周期请求
把以下请求体发送到POST /api/telemetry/analytics/lifecycle。它按 1 个事件对用户分类，而不是按项目中的所有活动：
history_period_count 设置 LogBrew 把 since 之前的多少个完整周期作为历史读取。它接受 2 到 31，默认为 2。用户可能在进行其他活动，但对这个事件而言仍处于休眠状态。
精确事件生命周期成功响应
这个模拟示例使用 2 天历史和 2 个分析日。字母只用来标识示例用户。响应不返回用户 ID。
C 在 6 月 2 日还浏览了一个页面。该事件不匹配结账选择器。
解读生命周期
6 月 1 日，A 为持续活跃，B 为重新活跃，C 为新增，D 为休眠。6 月 2 日，A 和 B 为持续活跃；C 虽然浏览了页面，但对结账而言处于休眠状态。6 月 2 日的净变化为2 - 3 = -1。
在每个时间桶中，新增、持续活跃和重新活跃的用户数相加等于 active_subjects。returning_subjects 加 dormant_subjects 等于 previous_active_subjects。net_active_change 等于 active_subjects 减去 previous_active_subjects。
不要把每日活跃数相加来得到去重用户数。这里每日计数相加为 5，但 analysis_active_subjects 为 3。历史和分析期间一共出现了 4 个不同的用户。
如果最后一个时间桶在 until 之后才结束，它的 fully_observed 为 false。等整个周期都可观测时，它的计数可能会变化。next_action 建议的是一个排查方向，并不表明原因。
自动生命周期
发送response_version: 2，且不发送 event 选择器。每个受支持的页面浏览、屏幕浏览和互动都算作活动：
summary、buckets 和 next_action 结构与精确事件响应相同。以下摘录显示有变化的字段：
coverage.selected_events 等于 coverage.analysis_classified_events。limitations 的第 5 项是 Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.
没有用户的生命周期
如果分析时间范围和历史中都没有可用的用户，buckets 为空，summary 省略 latest_fully_observed_period：
生命周期错误
除通用范围错误外，以下请求返回422 和 validation_failed：
例如，10 个
week 历史周期需要 70 天：
读取所选的分析范围
精确事件响应带有schema_version: 1。其 query 回显选择器，并省略 activity_scope。自动响应带有 schema_version: 2 和 query.activity_scope: "all_classified_activity"，并省略选择器。即使采集的活动没有任何变化，换一个选择器也可能改变结果。
指标序列响应
GET /api/telemetry/metrics/series 读取 1 个项目中 1 个准确的指标名称。从 GET /api/telemetry/metrics 复制该名称。以下请求按服务对一个 delta 计数器分组：
指标序列成功响应
这个模拟响应包含 1 个 delta 计数器序列。第一个时间桶中有 3 个样本，值为2、3 和 5。最后一个时间桶中有 2 个样本，值为 1 和 4。中间的时间桶没有样本，所以响应中没有它的数据点。
解读指标序列
第一个数据点记录的是 10 个已完成的任务，不是 10 个样本。rate_per_second 用这个变化量除以 300 秒的时间桶。last 是最后记录的变化量，不是总和。请参阅指标聚合的含义。
序列的类型和时间性决定了它的 aggregation.code 以及每个数据点中的统计值。数据点会省略不适用的统计值。缺失的统计值不是零。
limited 是成功响应，不是错误。它会增加 aggregation.limitation，说明 LogBrew 为什么只显示原始值。ready 不能证明采集完整。
绘制图表之前，先读取 coverage：
samples统计所有匹配序列的样本，包括响应没有返回的序列。series统计匹配的序列数。returned_series和points统计返回的数据。series_limit去掉了数量较少的序列时，truncated为true。expected_buckets_per_series是该时间范围内可能的时间桶数。
trace_exemplars。链路示例把 1 个样本关联到 1 条链路，不能解释该时间桶中的每个样本。如果没有数据点带有链路示例，next_action.target 为 metric_samples。
指标序列的范围与错误
project_id、name 和 since 为必填项。name 最多 200 个字符。interval 为 auto、1m、5m、15m、1h、6h 或 1d。默认为 auto，会选择所需时间桶不超过 300 个的最小间隔。显式指定的间隔所需的时间桶不能超过 500 个。
group_by 为 none、service_name、release 或 environment，默认为 none。不分组时，不同的类型、单位和时间性仍保留在各自的序列中。series_limit 接受 1 到 20，默认为 10。
空结果返回 200、series: [] 和为零的 samples。coverage 对象省略 first_seen_at 和 last_seen_at。这不能证明应用从未发送过该指标。检查项目、指标名称和时间范围。
省略 name 时返回 422：
422：
422 错误包括 metric series group_by is not supported、metric series interval is not supported 和 metric series_limit must be between 1 and 20。
路径分析响应
POST /api/telemetry/analytics/paths 查找同一会话中某个选定事件之前或之后的命名事件。这个选定事件就是锚点。从 classified_activity.top_events 复制它的 kind 和 event_name。该路由返回 schema_version: 1，不接受 response_version 或 analysis_unit。
direction 和 anchor 为必填项。
路径成功响应
在这个模拟结果中，有 4 个会话包含锚点。返回的 2 条路径代表其中 3 个会话。还有 1 条排名较低的路径没有返回。解读路径
share_of_anchored_sessions 用某条路径的会话数除以全部 4 个含锚点的会话。占比为 50% 和 25%，而不是 67% 和 33%。unrepresented_sessions 统计没有被任何返回路径代表的含锚点会话。paths_truncated: true 表示结果不完整。
覆盖率统计的是事件，不是会话。这里有 5 个事件匹配锚点，但其中 1 个没有会话 ID，所以无法进入路径。每条路径最多返回 3 个链路示例。使用你自己响应中的链路 ID。链路关联不能说明是什么导致了用户操作或故障。
两个方向的节点都按时间顺序排列。路径不是完整的会话回放。LogBrew 在选择锚点之前，每个会话最多读取 1024 个命名事件：
following 读取最早的事件，preceding 读取最晚的事件。超出这个上限的锚点可能会被省略。
按属性筛选锚点
最多发送 4 个property_filters，每个包含 1 个准确的 key 和 value。从属性目录复制键。筛选条件只作用于锚点，不作用于锚点周围的事件。值区分大小写。有筛选条件时，query 会回显它们，coverage.anchor_property_filters 会报告：
缺少键和值不同需要不同的修复方法。不要把它们加在一起。请求没有属性筛选条件时，会省略该对象。
空路径与被拒绝的请求
空的paths 数组可能是成功的 200 响应。读取 summary、coverage 和 next_action。以下代码可区分各种原因：capture_product_activity、choose_captured_path_anchor、capture_anchor_properties、improve_anchor_property_coverage、verify_anchor_property_values、sessionize_product_activity 和 narrow_or_move_path_anchor。
除通用范围错误外，以下请求返回 422 和 validation_failed：
例如，
depth: 0 返回：
分析属性目录
GET /api/telemetry/analytics/properties 列出 1 个项目中已分类产品事件上的属性键。在分群对比和路径锚点筛选条件中使用这些键。目录返回键和计数，从不返回属性值或身份信息。
读取可用的属性键
发送project_id 和 since。也可以发送 until、service_name、release、environment、limit 和 response_version。limit 接受 1 到 50 个键，默认为 20。发送 response_version=2 可以获取公开的 estimation.method 值。
属性目录成功响应
在这个模拟结果中，共有 100 个已分类事件。其中 5 个是在当前属性索引建立之前采集的。解读目录
标准上下文键（例如resource.runtime.name）的 source 为 standard_context，以 tag. 开头的键的 source 为 custom_tag。value_type 始终为 string。properties 按 events 从高到低排序。
100 个已分类事件中有 60 个带有 tag.plan。它大约有 3 个不同的值。描述信息不显示这些值。使用你在自己的应用中已知的值。不要根据计数猜测值。1 个事件可能有多个键，所以不要把每个键的 events 计数相加。
空的
properties 数组不能证明项目没有产品事件。读取 summary、coverage 和 next_action。
属性目录错误
除通用范围错误外，limit=0 或 limit=51 返回 422：
response_version 不是 1 或 2 时，返回 product analytics response_version must be 1 or 2。LogBrew 会先检查 response_version，再检查其他值。
POST 请求返回 405：
分析分群对比
POST /api/telemetry/analytics/segments/compare 比较 1 个项目中 2 到 4 个分群里的会话或用户到达某个准确事件的频率。分群按服务、版本、环境和属性值选择事件。第一个分群是基准。
定义对比
使用账号身份验证和Content-Type: application/json 发送以下 JSON 请求体。这里的 basic 和 premium 是示例应用的套餐值，不是 LogBrew 的套餐：
target 和 segments 为必填项。analysis_unit 为 session 或 identified_user。默认为 session，统计的是会话，不是人。interval 接受与概览相同的值，默认为 auto。
每个分群都需要唯一的 key、1 个 label 和一组不同的筛选条件：
key：1 到 32 字节。以小写 ASCII 字母或数字开头。只能使用小写 ASCII 字母、数字、_和-。label：1 到 80 个字符，不含控制字符。service_name、release、environment：可选。每个值为 1 到 256 个字符，不含控制字符。property_filters：0 到 4 个筛选条件。每个键在一个分群中只能出现 1 次。事件必须匹配该分群的所有筛选条件。值区分大小写，长度为 1 到 256 个字符，LogBrew 会去掉首尾空格。
分群对比成功响应
在这个模拟结果中，基准分群在 50 个会话中有 10 个到达结账。premium 分群在 60 个会话中有 18 个到达结账。解读比率和差异
eligible_units 估算分群中有已分类活动的会话数或用户数。reached_units 估算其中到达目标的数量。reach_rate 等于 reached_units 除以 eligible_units。没有所选单位 ID 的事件不计入这些单位。
基准比率为 20%，premium 比率为 30%。两者相差 10 个百分点。相对提升为 50%，而不是 10%。微小的小数误差来自浮点运算。显示时可以对比率取整，但计算时使用返回的值。基准分群没有 comparison_to_baseline。基准到达率为零时，会省略相对提升。
在 query 中，你没有发送的分群筛选条件为 null。空的 property_filters 列表会被省略。
coverage.property_filters 的字段与路径锚点筛选覆盖率相同。这里 matching_events 等于 classified_events。把缺少键和值不同分开处理。分群可以重叠，1 个会话可能出现在多个时间桶中。不要跨分群或跨时间桶相加单位计数。
这种对比是描述性的。confidence.causal_inference 为 not_established，confidence.statistical_significance 为 not_tested。30% 对 20% 并不能说明某个套餐带来了更多结账。
分群对比错误
除通用范围错误外，以下请求返回422 和 validation_failed：
interval 的错误与概览错误相同。
例如，2 个键不同但筛选条件相同的分群返回：
GET 请求返回 405：
信号数量响应
GET /api/telemetry/summary/volume 统计 1 个项目在某个时间范围内已保留的信号。它需要 project_id 和 since，不接受 project_ids。
until 不能是未来的时间。省略它时，结束时间为请求时间。24h 这样的简写 since 从 until 往前计算。interval 为 auto、1m、5m、15m、1h、6h 或 1d。默认的 auto 会选择时间桶不超过 120 个的最小间隔。请求所需的时间桶不能超过 500 个。response_version 只有 1。
信号计数
这个模拟响应涵盖 2 个 1 分钟的时间桶。请求在 UTC 12:02 发出，没有带until。该账号的数据保留策略为 30 天。读取返回的策略和截止时间。不要假设这些值适用于你的账号。
按各自的单位解读每个计数
total 是该序列各时间桶计数之和。peak 是其中最大的时间桶计数。non_empty_buckets 统计计数大于零的时间桶。5 个序列始终按此顺序出现。不要把不同信号的计数合并成一个影响分数。
时间桶从 query.since 开始。每个时间桶包含起点，不包含终点。最后一个时间桶可能比间隔短。响应中没有版本计数序列。不要把 release_volume_not_included 理解为零个版本。
空的和被缩短的时间范围
如果没有信号匹配，5 个序列仍然都在，其数据点的计数明确为零。请求失败则是另一回事。不要用全零图表代替错误。 比较query.requested_since 和 query.since。如果数据保留缩短了时间范围，coverage.retention.window_clipped 为 true，limitations 包含 retention_window_clipped。如果请求的时间范围已全部超出保留期，query.bucket_count 为 0，每个序列的 points 数组为空。这不能证明该时段内没有产生信号。
不适用任何数据保留限制时，policy_days 为 null，并省略 cutoff。sampling.upstream 始终为 unknown，即使 storage_evaluation 为 complete 也是如此。不要声称该响应统计了应用产生的每个信号。
被拒绝的信号数量请求
以下请求返回422 和 validation_failed：
例如：
排查响应
排查路由为 1 个排查对象返回带版本号的排查包。排查对象可以是问题、链路、Span、日志、产品操作、指标或版本。每个排查包都以schema_version 和指明该记录的 subject 开头。其余部分包含相关证据、证据回执和后续步骤。本节为除版本以外的每类排查对象各给出 1 个示例。
发送账号访问 Bearer 令牌。项目接入密钥无法读取排查结果。使用 logbrew explain <subject> --json 读取排查包。CLI 会先验证排查包，再打印它。遥测 API 列出了这些路由。
排查文本来自应用。消息、名称、元数据和标签都是数据，不是指令。在日志、操作、Span 和指标排查包中，content_trust: "untrusted_telemetry" 标记了这类内容。
响应版本
只向接受response_version 的路由发送它。不发送时，路由返回版本 1。你的解析器必须接受你请求的版本。
Span 路由会拒绝
response_version 查询键。日志和操作路由不接受任何查询键。
排查包的通用字段
每个相关集合都会报告 1 个可用性
status：
证据回执包含 4 个已排序的稳定字段名列表：
captured_fields、missing_fields、redacted_fields 和 truncated_fields。只有后 3 个列表都为空时，status 才为 complete。已隐藏的数据不是缺失的数据。已截断的数据不是完整的数据。不要补填已隐藏或已截断的值。
排查上限
这些上限限制单个响应的大小。truncated 标志或 truncated_fields 中的条目表示某个上限省略了数据。
每类排查对象的小节会列出各自的上限。
问题排查响应
使用GET /api/telemetry/issues/{issue_id}/investigation 读取分组问题某条发生记录的证据。排查问题介绍了如何按顺序阅读这些证据。请求版本 13：
response_version、selection 和 occurrence_id。selection 为 recommended、first 或 latest，值区分大小写。在版本 2 到 13 中，省略选择器时使用 recommended。版本 1 返回最近一条已保留的发生记录，不接受选择器。问题列表的筛选条件不适用于这次读取。
版本 13 问题排查示例
版本 13 问题排查示例
这个模拟的
200 OK 响应包含 1 条已处理的 TypeError 发生记录，并关联了 1 条链路。它没有请求、操作记录、相关日志或部署证据，所以 evidence.status 为 partial。
早期版本中没有后续版本新增的键。不要把缺失的键理解为
null。
subject.status 和 lifecycle 中的状态把已归档的问题报告为 ignored。问题列表和详情响应在响应版本 2 及以后使用 archived。
问题上限：推荐最多读取 50 条已保留的发生记录。趋势最多 30 个时间桶。每个分布最多返回 10 个值。每个堆栈最多 32 个帧。
问题排查请求错误
selection 和 occurrence_id 只能用其中一个。即使两者选择同一条发生记录，也不要同时发送：
找不到发生记录不代表问题不存在。
404 不表明其他账号能否读取该问题。
链路排查响应
使用GET /api/telemetry/traces/{trace_id}/investigation 读取 1 条链路及其失败路径、最慢路径和相关信号。查询键为 response_version、project_id、release 和 environment，都是可选的。请求版本 3：
cause 和 fix。版本 3 在采集到 span_id 时，把它添加到相关问题、操作和指标中。
版本 3 链路排查示例
版本 3 链路排查示例
这个模拟响应包含 1 个根服务端 Span 和 1 个失败的客户端 Span。失败的 Span 同时也是最慢的子 Span。这些 Span 没有结构化上下文，所以
spans.context 缺失。
如果某个 Span 指向的父 Span 未被 LogBrew 保留，
trace.parentage 会缺失。Span 预览最多包含 64 个 Span。每条分析路径最多包含 64 个 Span。相关读取最多使用 8 个部署范围。
目标为 trace_span 的下一步建议会指明本排查包中的某个 span_id。要读取该 Span，使用该 Span 的 project_id、environment 和 release 调用 Span 路由。
Span 排查响应
使用GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation 读取链路中的 1 个 Span。发送 project_id、environment 和 release，三者都是必填项。从所选的 Span 中复制它们。不要把 Span 行的 id 当作 span_id 发送。
Span 排查示例
Span 排查示例
这个模拟响应描述链路示例中失败的客户端 Span。有 1 条错误日志具有相同的 Span ID。该 Span 的耗时超过了其已保留同类 Span 的近似第 95 百分位数。
基准读取 Span 开始前的 24 小时。包含
since，不包含 until。error_rate_basis_points: 500 表示 5%。subject_percentile_basis_points: 9500 表示 95% 的已保留同类 Span 耗时不超过该 Span。百分位数是近似值。把 baseline.limitations 与这些值放在一起保留。not_found 基准表示没有已保留的同类 Span。unavailable 基准表示读取失败，不是零计数。
parent_chain_status: "complete" 表示已保留的父级链能追溯到根 Span。它不能证明 LogBrew 保留了该请求的每个 Span。拓扑最多返回 64 个祖先 Span、50 个直接子 Span 和 50 条跨服务边。
日志排查响应
使用GET /api/logs/{log_id}/investigation 读取 1 条日志及其相关证据。该路由没有查询键。从日志列表中复制日志 ID。
日志排查示例
日志排查示例
这个模拟响应包含 1 条没有链路上下文的警告日志和 1 条附近日志。响应不会根据时间戳构造链路关联。
链路状态为
not_found 或 unavailable 时，链路 ID 也可能存在。有可用的链路摘要并不保证有 exact_span。
操作排查响应
使用GET /api/telemetry/actions/{action_id}/investigation 读取 1 个产品操作、它报告的状态和相关证据。该路由没有查询键。相关读取的时间范围和范围条件与日志排查相同。
correlations、timeline 和 next_actions 使用日志排查的结构。相关操作不含被排查的操作本身。
操作排查示例
操作排查示例
这个模拟响应描述一位已登录用户的结账操作失败。该操作没有链路 ID。
响应从不返回主体或会话标识符。证据回执始终把
subject.distinct_id 列为已隐藏；采集到会话时，还会列出 subject.session_id。因此，每个操作排查包都是 partial，并包含 improve_capture。不要为了满足它而移除隐私控制。
指标排查响应
使用GET /api/telemetry/metrics/investigation 读取 1 个项目在某个时间范围内的 1 个指标名称。响应包含当前序列、与前一个等长时间范围的比较、最新样本、链路示例和已完成的部署。版本 2 添加来自最近一个已保留样本的指标描述。版本 1 始终报告 description_status: "not_captured"。
project_id、name 和 since 为必填项。包含 since，不包含 until。until 默认为当前时间。比较还会读取前一个等长的时间范围。
版本 2 指标排查示例
版本 2 指标排查示例
这个模拟直方图在 2 个 5 分钟的时间桶中有 5 个样本。最近的时间桶的 p95 为 48 ms。前一个时间范围中最近的时间桶的 p95 为 24 ms。
relative_change_percent 等于 (current - previous) / abs(previous) * 100。前一个值为零或缺失时，它为 null。expected_buckets_per_series 统计的是可能的时间桶，不是有数据的时间桶。不要把空的时间桶画成零。变化附近有部署，不能证明是该部署导致了变化。
账号无法读取的项目会返回 200 OK 和 analysis.status: "no_samples"，而不是 404。空结果不描述其他信号类型。
指标上限：时间范围最长 31 天。每个序列最多 500 个时间桶。series_limit 为 1 到 20，默认为 10。响应最多返回 20 个链路示例和 20 个部署。
interval 为 auto、1m、5m、15m、1h、6h 或 1d。group_by 为 none、service_name、release 或 environment。其他值返回 422。
排查错误
404 表示没有可读取的项目包含该记录。每个路由在缺少有效身份验证时还会返回 401，在使用 GET 以外的方法时返回 405。未找到、路径、身份验证和方法响应请参阅 API 错误。
可选的证据读取可能在 200 OK 响应内部失败。此时该集合报告 unavailable。不要把它显示为 not_found 或零条记录。
严重程度值
面向用户的严重程度值为info、warning、error 和 critical。SDK 和运行时可以发送常见别名，例如 trace、debug、warn 或 fatal。REST 和实时响应始终返回规范值。例如，LogBrew 接受输入的 warn，并返回 warning。数据接收会拒绝未知的严重程度值。
严重程度规则响应
严重程度规则会改变 LogBrew 显示日志或问题的方式，但不会改变应用采集时的严重程度。日志和问题会返回triage 对象：
显示时使用
triage.effective_severity。把 severity 保留为采集时的值。日志列表默认省略已忽略的日志。要包含它们，在 GET /api/logs 上发送 status=ignored 或 status=all。
账号必须有权管理该项目中的问题，只有读取权限是不够的。没有该权限时，规则更改返回 403 和 code: forbidden。
更改日志规则
PUT /api/logs/{log_id}/triage-rule 为该日志以及之后具有相同签名的日志设置规则。请求体需要同时包含 severity 和 ignored：
200 OK 响应包含完整的日志。其 severity 仍为 warning，triage 显示该规则：
severity 为 source、info、warning、error 或 critical。source 会恢复采集时的严重程度，但不会让已忽略的日志重新生效。要再次显示该日志，发送 "ignored": false。
更改问题规则
PUT /api/telemetry/issues/{issue_id}/triage-rule 设置分组问题及其之后发生记录的显示严重程度。请求体只接受 severity：
200 OK 响应包含版本 1 的完整问题。采集时的 severity 和 status 不会改变：
response_version=2 或 3 读取问题即可看到它。
不支持的严重程度返回 422：
status）返回 422 和 code: invalid_json。不存在或无法读取的日志或问题返回 404 和 code: not_found。如果响应丢失，先重新读取日志或问题，再重新发送规则。
错误响应格式
应用错误返回 JSON 封装。以下示例是一个被拒绝的请求；error 和 next 文本取决于具体错误：
code 做程序分支，用 next_action 做自动化。把 error 和 next 作为纯文本展示给用户。不要解析它们的措辞。有些错误会添加字段，例如 limit、reset_at 或 retry_after_seconds。没有 JSON 响应体的响应不含 LogBrew code。所有错误码请参阅 API 错误。
使用 CLI 读取数据
CLI 读取相同的路由，并在使用--json 时返回相同的 JSON。先宽泛查询，再逐步缩小范围：
--pagination cursor 可以获取游标封装。CLI 请求的是问题响应版本 4。请参阅读取下一页和实时查看。