> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 可观测性术语表和 LogBrew 术语

> 查询 LogBrew 的信号类型、项目范围、身份、证据状态和产品分析术语。

LogBrew 的每个产品概念只用一个术语。API 字段、CLI 选项、枚举值、事件名称和属性键在所有语言中都保持不变。

## 可观测性和监控

| 术语 | 含义 |
| - | - |
| 可观测性 | 通过应用产生的证据理解它的行为。 |
| 遥测 | 应用上报的信号，例如日志、链路和指标。 |
| 监控 | 检查已知的条件，例如把测量值与阈值比较。 |
| `o11y` | observability（可观测性）的英文缩写。数字表示 `o` 和 `y` 之间的 11 个字母。 |

如何选择信号以及完整示例，请参阅[遥测](/zh-Hans/concepts/telemetry)。

## AI 智能体

| 术语 | 含义 |
| - | - |
| MCP 服务器 | LogBrew 托管的 Model Context Protocol 服务器。AI 智能体通过它读取已批准的项目。 |
| MCP 客户端 | 把 AI 智能体连接到 MCP 服务器的应用，例如 Claude Code。 |
| 已批准的项目 | 你在授予 MCP 客户端访问权限时选择的项目。客户端只能读取已批准的项目。 |
| 连接 | 你在批准某个 MCP 客户端时授予它的访问权限。连接在 30 天未使用后、90 天后或被你撤销时结束。CLI 中称为 grant（授权）。 |

要连接客户端，请参阅[通过 MCP 连接 AI 智能体](/zh-Hans/guides/mcp)。

## 可观测性信号

<AccordionGroup>
  <Accordion title="问题">
    按分组归并的故障，可以包含多条发生记录。发生记录是该问题被采集到的一次实例。`first_seen_at` 是第一条发生记录的时间。`last_seen_at` 是最近一条发生记录的时间。
  </Accordion>

  <Accordion title="日志">
    一条带时间戳的事件记录。日志可以携带严重程度、服务、版本、环境、链路上下文，以及受隐私限制的属性。
  </Accordion>

  <Accordion title="链路和 Span">
    链路记录一次请求或操作经过的各个环节。Span 是链路中的一次计时操作。与某条链路关联，说明存在共享的上下文，但不能证明因果关系。
  </Accordion>

  <Accordion title="指标">
    运行时测量值，具有明确的单位、类型、聚合方式和时间范围。指标点不能与日志、链路或问题的计数互换。
  </Accordion>

  <Accordion title="版本">
    随遥测数据上报的、已部署的应用或服务版本。版本与项目或仓库不是同一个对象。
  </Accordion>

  <Accordion title="操作">
    经过分类的产品事件，例如注册、结账、导入或失败的任务。分析功能把操作分为页面浏览、屏幕浏览或互动。操作不是 LogBrew 自动运行的命令。
  </Accordion>
</AccordionGroup>

## 问题排查

并非每条发生记录都包含所有字段。

| 术语 | 含义 |
| - | - |
| 严重程度 | 信号的紧急程度：`info`、`warning`、`error` 或 `critical`。它独立于问题状态。 |
| 问题状态 | 分组问题所处的工作流状态：`unresolved`、`resolved` 或 `archived`。它不是某次请求的结果。 |
| 已归档问题 | 团队已移出分诊队列的问题。旧版响应把此状态称为 `ignored`。 |
| 问题优先级 | 分组问题的分诊顺序：`high`、`medium` 或 `low`。在有人手动设置之前，它跟随严重程度。 |
| 优先级来源 | 优先级从何而来。`derived`（自动推导）跟随严重程度：`error` 和 `critical` 为 `high`，`warning` 为 `medium`，`info` 为 `low`。`manual`（手动设置）表示由人设置的优先级。 |
| 问题负责人 | 负责分组问题下一步工作的 1 个账号或 1 个团队。账号必须能读取项目，团队必须属于项目所在的组织。 |
| 团队 | 组织中有名称的一组成员。问题可以分配给团队，所有权规则也可以指定团队。加入团队不会让成员获得项目访问权限。 |
| 所有权规则 | 项目中的一条规则，把堆栈帧路径、模块、路由、服务或标签对应到匹配问题的所有者，即账号或团队。 |
| 建议所有者 | LogBrew 为问题推荐的账号或团队，依据是所有权规则、CODEOWNERS 中的某一行或近期活动。这只是建议，不是分配。 |
| 收件箱 | 其他人分配给你或你所在团队的问题列表。LogBrew 不会为此发送邮件。 |
| 堆栈跟踪 | 为错误采集的函数调用证据。它不同于链路追踪中的链路。 |
| 堆栈帧 | 堆栈跟踪中的一个条目。它可以标识函数、模块、文件、行或列。 |
| 异常链 | 一起上报的相互关联的异常，例如一个错误及其原因。缺失、已隐藏或已截断的条目会限制证据。 |
| 应用代码帧 | 被标记为应用代码的堆栈帧。它指出需要检查的代码。它不能证明故障所在。 |
| 操作记录（Breadcrumbs） | 问题发生记录之前记录的简短事件。操作记录不是会话的完整记录。 |
| 已处理的异常 | 应用上报为已处理的异常。它不能证明该操作成功。 |
| Source Map | 一种构建产物，把生成后的 JavaScript 位置映射到原始源码位置。 |
| 已符号化的帧 | 生成后的位置已解析为原始源码信息的堆栈帧。 |
| 基准发生记录 | 作为复现参考的已采集发生记录。 |
| 来源 | 某项判断的来源。`backend_observed` 表示由 LogBrew 观察到。`application_reported` 表示由应用上报，LogBrew 未验证。 |
| 复现就绪状态 | 基准发生记录是否具备尝试复现所需的证据。它不代表复现测试已通过。 |

阅读顺序和响应字段见[排查问题](/zh-Hans/guides/investigate-an-issue)。

## 身份和关联

值缺失并不能证明相关活动没有发生。

| 术语 | 含义 |
| - | - |
| 链路上下文 | 把各个信号中的工作串联起来的 Trace ID 和 Span ID。 |
| 根 Span | 开启一条链路、没有父 Span 的 Span。返回的最早的 Span 不一定是根 Span。 |
| 子 Span | 在同一条链路中有父 Span 的 Span。 |
| 关联 | LogBrew 返回的确切关系，例如共享的 Trace ID。它不能证明因果关系。 |
| 已识别用户 | 应用提供的、带有稳定 ID 且类型为 `user` 的主体。 |
| 匿名主体 | 应用提供的、类型为 `anonymous` 的主体。计数时与已识别用户分开统计。 |
| 未知身份类型 | 没有已知类型的主体。它不计为已识别用户。 |
| 缺失主体 | 没有主体的事件。这与类型未知的主体不同。 |

身份类型说明应用如何为主体分类。它不能证明数据是匿名的。稳定的 ID 仍然可以把活动关联起来。

## 范围和数据质量

| 术语 | 含义 |
| - | - |
| 项目 | 首要的产品归属边界。一个项目可以包含多个服务或仓库组件。 |
| 服务 | 项目中负责上报的运行时或组件。 |
| 环境 | 确切的上报上下文，例如生产环境或预发布环境。 |
| 已接收 | 已按接收约定被接受。它不承诺无限期保留。 |
| 已索引 | 可以通过指定的索引或查询获取。它不是“已接收”的同义词。 |
| 已保留 | 存在于所评估的数据时间范围内。 |
| 已采样 | 部分遥测数据在采集之前或采集过程中被选中。 |
| 覆盖率 | 有明确分子和分母的测量占比。 |
| 已截断 | 响应达到了上限。被省略的数据不一定不存在。 |
| 近似 | 按文档所述方法估算，而不是精确计数。 |
| 时间范围 | 查询所评估的确切时间段。 |

## 测量和时间

| 术语 | 含义 |
| - | - |
| 数据点 | 某个上报时间的一个值。比较数据点之前，先看指标名称和单位。 |
| 时间序列 | 同一测量按时间排序的值。出现空缺不代表值为零。 |
| 耗时 | 一次操作经过的时间。它不同于操作发生的时间。 |
| 聚合 | 对多个测量值进行的确定计算，例如求和或求平均值。 |
| 时间桶 | 图表或分组结果中的一个区间。它的起止时间决定了范围。 |
| 不完整周期 | 尚未结束的周期。它不是一个活动为零的完整周期。 |

不要把相互重叠的子 Span 的耗时相加来得到请求总耗时。不要把事件数与已识别用户数进行比较。

## 证据状态

以下状态不能互换：

* **已采集**：证据存在。
* **缺失**：证据未被采集。
* **已隐藏**：证据被有意隐藏。
* **已截断**：证据超出了响应或采集的上限。
* **不可用**：读取无法提供该证据。

`Likely cause`（可能原因）和 `likely fix area`（可能的修复位置）描述的是有限的诊断证据，而不是已证实的根本原因。除非接口约定明确说明这是 LogBrew 的测量值，否则 `Reported impact`（报告的影响）由上报的应用提供。

## 产品分析

| 术语 | 含义 |
| - | - |
| 事件 | 有确切稳定名称、经过分类的产品活动。 |
| 属性 | 用于描述或筛选事件的上下文键。 |
| 会话 | 一次访问或一次应用会话，而不是一个人。 |
| 群组 | 按确切条件定义的有限群体。 |
| 漏斗 | 用于衡量推进或转化情况的有序步骤。 |
| 留存 | 用明确的周期和分母衡量的回访行为。 |
| 路径 | 所选事件之前或之后的会话路径。 |
| 生命周期 | 在每个周期内，把已识别主体分为在观测历史中为新增、持续活跃、重新活跃或休眠。 |
| 在观测历史中为新增 | 在有限的历史时间范围内处于活跃状态，且此前没有所选事件。它并不表示首次成为客户。 |

不完整周期、缺失的身份、不完整的属性采集、采样和截断都会限制结果的含义。LogBrew 会把这些限制展示出来，而不是把它们变成零或确定的结论。

计数规则见[产品分析](/zh-Hans/concepts/product-analytics)。要发送分类后的活动和带类型的身份，请参阅[产品事件采集](/zh-Hans/guides/product-events)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.