# Telemetry 设计

状态: Superseded
取代说明: 本文已被 `telemetry-minimum.md` 全面取代，仅保留历史设计参考；现状以 `telemetry-minimum.md` 与代码为准。
读者: 产品负责人、核心开发者、doclib server 开发者、数据分析与合规参与者
范围: 下一代 MinerU 的匿名使用统计、稳定性指标和粗粒度环境画像
非目标: 计费、审计、安全风控、精确故障追踪、上传文档内容或用户输入

## 1. 目标

Telemetry 的首要目标是产品使用统计，用于评估 MinerU 的使用规模和产品影响力。

P0 同时兼顾三类问题:

1. 产品使用统计: 有多少安装实例在使用、每天使用多少次、处理了多少文件和页面。
2. 质量与稳定性: 哪些主链路失败、失败发生在哪个阶段、错误码分布如何。
3. 性能与环境画像: 不采集细粒度设备指纹，只用粗粒度字段理解运行环境和处理规模。

Telemetry 数据只用于趋势分析和产品改进，不用于计费、安全判断或强一致审计。

## 2. 采集边界

只有 doclib server 上报 telemetry。

`mineru` CLI 依赖 doclib server，因此可以被间接统计。以下纯工具无 telemetry 能力:

- parser SDK，包括 `mineru.parser.parse()` 和 `parse_async()`
- `mineru-kit parse`
- `mineru-kit api-server`
- 其他不依赖 doclib server 的专家工具

这个边界避免 parser/tool 层在作为库或底层工具使用时包含 telemetry 相关配置、存储或网络行为。

## 3. 默认策略

首次启动 doclib server 时，必须要求用户完成 telemetry 选择。

默认行为:

- 首次选择界面不预选开启或关闭。
- 用户可以关闭。
- 用户选择结果记录为 `consent_state`。
- 用户关闭 telemetry 后，不再记录新的 telemetry metrics，也不再上报。
- 关闭时，DB 中未上报 telemetry 数据应删除，避免后续误发。

用户必须可以通过命令查看和修改状态:

```bash
mineru telemetry status
mineru telemetry enable
mineru telemetry disable
mineru telemetry preview
mineru telemetry flush
```

`preview` 应展示将要上报的 JSON，但不得展示任何 token 或服务端内部凭据。

## 4. 隐私边界

Telemetry 禁止采集:

- 文档内容
- 文件名
- 文件路径
- 原始 URL
- search query
- prompt
- sha256
- job_id
- parse_id
- traceback
- exception message
- hostname
- 用户名
- 邮箱
- 账号 ID
- CPU/GPU 具体型号
- GPU 显存、驱动版本、CUDA 版本

允许采集的数据必须来自白名单字段。不得把请求体、异常对象、配置对象、`kwargs` 或任意字典直接透传到 telemetry。

## 5. 统计口径

P0 使用匿名 `installation_id` 作为主统计口径。

- `installation_id` 在 doclib server 首次启用 telemetry 时生成。
- `installation_id` 存储在 doclib DB 的 telemetry 内部状态中。
- 不依赖账号体系。
- 用户删除配置或重装后，会被视为新的安装实例。

服务端基于 `installation_id` 计算:

- 安装量: 出现过的唯一 `installation_id`
- DAU: 当日有 telemetry 上报的唯一 `installation_id`
- WAU / MAU: 对应周期内有 telemetry 上报的唯一 `installation_id`

如果未来引入账号，账号只能作为可选维度，不替代 `installation_id`。

## 6. 上报模型

P0 采用本地聚合 metrics 上报，不采用每个事件即时上报。

运行时行为:

```text
doclib server runtime
  -> record metric delta
  -> update telemetry aggregate in doclib DB
  -> periodic flush
  -> POST telemetry endpoint
  -> delete flushed rows from doclib DB after success
```

建议聚合窗口:

- 本地 telemetry 配置和 telemetry 聚合数据都存储在 doclib DB 中。
- 本地按 1 小时 period 聚合。
- 上报时可以一次提交多个未 flush 的小时级 period。
- 启动后尝试 flush 一次。
- 运行中每 24 小时尝试 flush 一次。
- 网络失败或服务端 5xx 时保留本地聚合结果，后续重试。
- 服务端 4xx 表示 payload 不合法，对应 batch 应丢弃或进入本地失败记录，不应无限重试。
- flush 成功后，已被服务端确认接收的 telemetry 聚合数据应从 doclib DB 中删除。
- 同一个 period 内 context 变化可以接受；P0 flush 时使用当前 context 上报该 period 的聚合 metrics。

主流程不得等待 telemetry 上报。telemetry 失败不得影响 parse、watch、search 或 doclib API。

## 7. Endpoint

建议使用独立 telemetry endpoint:

```http
POST https://telemetry.mineru.net/v1/metrics
Content-Type: application/json
```

不建议与 `mineru.net/api` 的 parse API 混在一起，因为 telemetry 的认证、限流、存储和合规策略不同。

响应示例:

```json
{
  "object": "telemetry_metrics_result",
  "accepted": 42,
  "rejected": 0,
  "server_time": "2026-06-10T12:00:00Z"
}
```

如果服务端支持部分拒绝，可以返回:

```json
{
  "object": "telemetry_metrics_result",
  "accepted": 40,
  "rejected": 2,
  "errors": [
    {
      "index": 5,
      "code": "invalid_dimension",
      "message": "dimension value is not allowed"
    }
  ],
  "server_time": "2026-06-10T12:00:00Z"
}
```

错误信息只用于解释 schema 问题，不应包含用户上报原文中的敏感字段。

## 8. Payload 结构

一次上报包含一个 batch。环境信息放在 batch-level `context` 中，不重复放入每个 metric。

```json
{
  "batch_id": "tb_01HX...",
  "schema_version": "1",
  "installation_id": "inst_01HX...",
  "period_start": "2026-06-10T14:00:00Z",
  "period_end": "2026-06-10T15:00:00Z",
  "context": {
    "app": "mineru",
    "app_version": "3.0.0",
    "os": "macos",
    "arch": "arm64",
    "python_version": "3.11",
    "install_channel": "pip",
    "cpu_count_bucket": "9_16",
    "gpu_vendor": "apple"
  },
  "metrics": [
    {
      "name": "parse.completed.count",
      "value": 12,
      "dimensions": {
        "source": "cli",
        "caller": "agent",
        "tier": "basic(default)",
        "status": "succeeded"
      }
    },
    {
      "name": "parse.processed_page_count",
      "value": 1240,
      "dimensions": {
        "source": "cli",
        "caller": "agent",
        "tier": "basic(default)"
      }
    }
  ]
}
```

规则:

- `batch_id` 由本地 flush 任务生成，用于服务端短窗口幂等。
- `value` 必须是非负数。
- 字符串数据只能出现在 `context` 或 `dimensions`。
- `context` 描述安装实例、运行环境和版本。
- `metrics[].dimensions` 描述当前 metric 的业务分类。
- `metrics[].dimensions` 必须来自白名单，不能包含任意字符串。
- `context` 表示 flush 时 doclib server 的当前运行环境。同一 period 内 context 变化可以接受，不要求拆分 batch。

## 9. Context 字段

P0 context 字段:

| 字段 | 类型 | 枚举 / 格式 | 说明 |
|------|------|-------------|------|
| `app` | string | `mineru` | 固定应用名 |
| `app_version` | string | semver 或发布版本 | MinerU 版本 |
| `os` | string | `macos` / `windows` / `linux` / `other` / `unknown` | 操作系统 |
| `arch` | string | `x86_64` / `arm64` / `other` / `unknown` | CPU 架构 |
| `python_version` | string | `3.10` / `3.11` / `3.12` / `3.13` / `other` / `unknown` | Python 主次版本 |
| `install_channel` | string | `pip` / `uv` / `docker` / `source` / `unknown` | 安装来源 |
| `cpu_count_bucket` | string | `1_4` / `5_8` / `9_16` / `gt_16` / `unknown` | CPU 核心数分桶 |
| `gpu_vendor` | string | `nvidia` / `apple` / `amd` / `none` / `unknown` | GPU 或常见加速器厂商 |

`gpu_vendor` 规则:

- `nvidia`: 识别到 NVIDIA GPU。
- `apple`: 识别到 Apple GPU。
- `amd`: 识别到 AMD GPU。
- `none`: 明确没有发现 GPU。
- `unknown`: 无法检测、检测失败，或发现了 P0 未分类的其他加速器。

P0 不采集 CPU/GPU family、具体型号、显存、驱动和 CUDA 版本。

## 10. Metric 与 Dimension 规则

Metric 的 `name` 表示数值指标，`value` 表示计数或数值累加。

字符串型信息必须作为 dimension:

```json
{
  "name": "parse.completed.count",
  "value": 1,
  "dimensions": {
    "tier": "basic",
    "status": "succeeded"
  }
}
```

不允许:

```json
{
  "name": "parse.tier",
  "value": "basic"
}
```

Dimension 只允许低基数字段:

| 字段 | 枚举 / 说明 |
|------|-------------|
| `source` | `http_api` / `sdk` / `cli` / `mcp` / `web` / `app` / `watch` / `background` / `unknown` |
| `caller` | `agent` / `user` / `http_client` / `sdk` / `web` / `app` / `system` / `unknown` |
| `tier` | `default` / `flash` / `basic` / `standard` / `advanced` / `basic(default)` / `standard(default)` / `advanced(default)` / `unknown` |
| `status` | `succeeded` / `failed` / `partial` / `canceled` |
| `input_type` | `pdf` / `csv` / `tsv` / `rtf` / `docx` / `pptx` / `xlsx` / `odt` / `ods` / `odp` / `html` / `other` / `unknown` |
| `output_format` | `middle_json` / `markdown` / `structured_content` / `other` |
| `stage` | `enqueue` / `cache_lookup` / `parse_server_call` / `parsing` / `merge_pages` / `persist` / `index` / `unknown` |
| `error_code` | 稳定错误码枚举，不允许 exception message |
| `retryable` | `true` / `false` / `unknown` |
| `bucket` | 当前 metric 定义的分桶值 |
| `server` | `local(flash)` / `local(managed)` / `local(self-hosted)` / `remote(official)` / `remote(custom)` / `none` / `unknown` |
| `rule_type` | `exclude` / `parsing` / `unknown` |
| `remote` | `true` / `false` / `unknown` |
| `command` | 当前 metric 定义的命令枚举 |
| `wait_mode` | `sync` / `async` / `unknown` |
| `wait_bucket` | `0` / `1_10s` / `11_60s` / `gt_60s` / `unknown` |
| `page_range_mode` | `all` / `partial` / `default` / `unknown` |
| `config_area` | `watch` / `exclude` / `parsing_rules` / `parse_server` / `telemetry` / `unknown` |
| `cleanup_target` | `orphan_docs` / `deleted_files` / `temp` / `mixed` / `unknown` |
| `dry_run` | `true` / `false` / `unknown` |

`caller` 与 `source` 语义不同:

- `source` 表示请求从哪个调用通道进入 doclib，例如 HTTP API、SDK、CLI、MCP、Web、App、watch 或后台任务。
- `caller` 表示发起行为的主体，例如 Agent、用户、HTTP client、SDK、Web、App 或系统后台任务。

Agent 时代的核心产品目标要求 telemetry 能区分 `agent` 与 `user`。因此，CLI 通道必须尽量识别真实调用主体。

调用通道与主体规则:

| 使用方式 | `source` | `caller` |
|----------|----------|---------------|
| 直接调用 HTTP API，且未传 caller 信息 | `http_api` | `http_client` |
| Doclib SDK | `sdk` | `sdk` |
| `mineru` CLI，由 Agent 进程调用 | `cli` | `agent` |
| `mineru` CLI，由用户 shell 调用 | `cli` | `user` |
| `mineru` CLI，无法可靠判断父进程 | `cli` | `unknown` |
| MCP Server | `mcp` | `agent` |
| Web | `web` | `web` |
| 桌面 App | `app` | `app` |
| watch 自动发现 | `watch` | `system` |
| compaction / cleanup / health check 等后台任务 | `background` | `system` |

CLI 的 `caller` 可以通过父进程识别。若父进程是 Claude Code、Codex 等已知编程 Agent，则记为 `agent`；若父进程是普通 shell 或终端，则记为 `user`；无法可靠判断时记为 `unknown`。不得通过文件路径、命令文本、query、prompt、文档内容或具体会话内容推断。

`tier` 同时表达请求档位和实际解析档位:

- 用户未指定 tier，且尚未解析到实体 tier 时，使用 `default`。
- 用户显式指定实体 tier，或任务已经完成且没有必要保留默认来源时，使用 `flash`、`basic`、`standard` 或 `advanced`。
- 用户未指定 tier，且已经解析到实体 tier，同时仍需要保留来源信息时，使用 `basic(default)`、`standard(default)` 或 `advanced(default)`。
- 默认选择不会解析为 `flash`，因此不定义 `flash(default)`。
- parse-server 相关 metric 也使用同一个 `tier` 维度，不再单独使用 `parse_server_tier`。

`server` 表达解析执行位置和服务形态:

- `local(flash)`: 本地 flash 解析，不经过 parse-server。
- `local(managed)`: doclib 管理的本地 parse-server。
- `local(self-hosted)`: 用户自行启动的本地或自部署 parse-server。
- `remote(official)`: 官方 `mineru.net/api`。
- `remote(custom)`: 用户显式配置的其他远端兼容 parse-server。
- `none`: 当前行为没有解析服务，例如 cache hit、查询类操作或本地 parse-server disabled 配置状态。
- `unknown`: 无法可靠判断。

`parse_server.*` metric 不使用 `server=local(flash)`，因为 flash 不经过 parse-server。`parse.*` metric 可以使用 `server=local(flash)` 表示显式 flash 本地解析。

## 11. Metric 候选全集

Telemetry 记录业务行为，不记录所有 HTTP 请求。状态查询、健康检查、列表读取和普通配置读取默认不计入 telemetry。

本节列出第一版候选全集。后续实现前可以按 P0 范围裁剪，但裁剪后的实现必须仍能回答产品使用规模、核心链路稳定性和主要性能瓶颈。

`parse.*` 与 `parse_server.*` 的语义边界:

- `parse.*` 统计 doclib 解析业务生命周期，回答用户是否发起解析、缓存是否命中、任务是否完成、处理了多少文件和页面、最终状态如何。
- `parse_server.*` 统计 doclib 解析业务生命周期中调用 parse-server 的执行片段，回答是否实际使用 parse-server、使用 local 还是 remote、使用什么模式和 tier、该执行片段的请求数、处理量、失败率和耗时。
- 一次 parse 请求可以产生 `parse.*`，但不一定产生 `parse_server.*`。例如 cache hit、显式 `flash` 本地解析、复用已有完成批次时，通常不产生 parse-server 执行指标。
- 一次 parse 请求如果实际调用了 local 或 remote parse-server，则同时产生 `parse.*` 和 `parse_server.*`。两者不能互相替代。
- `parse.duration.bucket.count` 统计 doclib parse 业务生命周期耗时；`parse_server.duration.bucket.count` 只统计 doclib 调用 parse-server 的执行片段耗时。

产品使用统计:

| Metric | 说明 |
|--------|------|
| `server.started.count` | doclib server 启动次数 |
| `server.shutdown.count` | doclib server 正常关闭次数 |
| `server.recovered_stale_lock.count` | doclib server 启动恢复 stale lock 的次数 |
| `cli.command.count` | `mineru` CLI 子命令调用次数 |
| `server.command.count` | `mineru server` 生命周期命令调用次数 |
| `ingest.requested.count` | 入库请求次数 |
| `ingest.completed.count` | 入库成功次数 |
| `ingest.duplicate.count` | 入库时发现内容已存在的次数 |
| `parse.requested.count` | parse 请求次数 |
| `parse.completed.count` | parse 完成次数，按 `status` 区分成功、失败、部分成功和取消 |
| `parse.files.count` | parse 处理文件数 |
| `parse.processed_page_count` | parse 处理页数；数值统计，不是页面列表 |
| `parse.output.requested.count` | parse 请求输出格式次数 |
| `parse.output.to_stdout.count` | parse 输出到 STDOUT 的次数 |
| `parse.output.to_file.count` | parse 输出到文件的次数 |
| `parse.marker.disabled.count` | 用户通过 `--no-marker` 禁用 marker 的次数 |
| `parse.wait_mode.count` | parse 同步或异步等待模式使用次数 |
| `parse.page_range.requested.count` | parse 请求页码范围模式使用次数 |
| `parse.force.count` | 用户通过 `--force` 请求重新解析的次数 |
| `parse.created_batch.count` | 本次请求创建的新 parse batch 数 |
| `parse.active_reused.count` | 本次请求复用 pending/parsing batch 的次数 |
| `parse.waited_batch.count` | 本次请求等待的 parse batch 数 |
| `watch.files.discovered.count` | watch 发现文件数 |
| `watch.files.parsed.count` | watch 自动解析文件数 |
| `rules.matched.count` | rule 命中次数 |
| `rules.excluded.count` | exclude rule 排除文件次数 |
| `rules.parse_rule_applied.count` | parsing-rule 被应用次数 |
| `search.performed.count` | search 次数，不采集 query |
| `find.performed.count` | find 文件名搜索次数，不采集 query |
| `doclib.content.requested.count` | 请求读取或渲染文档内容的次数 |
| `doclib.content.rendered.count` | 内容读取时成功渲染输出格式的次数 |
| `doclib.content.truncated.count` | 内容输出因 token/page budget 被截断的次数 |
| `doclib.content.continuation_requested.count` | 用户或 Agent 请求 continuation 的次数 |
| `doclib.docs.added.count` | doclib 新增文档数 |
| `search.index.updated.count` | 搜索索引更新次数 |
| `search.index.source_tier.count` | 搜索索引来源 tier 计数 |
| `parse.cache.hit.count` | parse cache 命中次数 |
| `parse.cache.miss.count` | parse cache 未命中次数 |
| `remote.requested.count` | 用户显式请求 remote 的次数 |
| `remote.allowed.count` | remote 请求被隐私策略允许的次数 |
| `config.watch.added.count` | watch 目录添加次数 |
| `config.watch.removed.count` | watch 目录移除次数 |
| `config.rule.added.count` | exclude 或 parsing rule 添加次数 |
| `config.rule.removed.count` | exclude 或 parsing rule 移除次数 |
| `config.parse_server.changed.count` | parse-server 配置变更次数 |
| `parse_server.configured.count` | doclib server 启动或配置变化时记录当前 parse-server 配置 |
| `parse_server.local.started.count` | managed 本地 parse-server 被 doclib 拉起的次数 |
| `parse_server.local.restarted.count` | managed 本地 parse-server 被重启的次数 |
| `parse_server.requested.count` | doclib 调用 parse-server 的请求次数 |
| `parse_server.completed.count` | doclib 调用 parse-server 成功完成次数 |
| `parse_server.files.count` | parse-server 处理文件数 |
| `parse_server.processed_page_count` | parse-server 处理页数；数值统计，不是页面列表 |
| `parse.compaction.completed.count` | parse 批次 compaction 成功次数 |
| `cleanup.deleted_files.count` | cleanup 删除文件数 |
| `cleanup.orphan_records.count` | cleanup 清理孤儿记录数 |

质量与稳定性:

| Metric | 说明 |
|--------|------|
| `ingest.failed.count` | 入库失败次数 |
| `parse.failed.count` | parse 失败次数 |
| `parse.partial.count` | parse 部分成功次数 |
| `parse.retry.count` | parse 重试次数 |
| `parse.timeout.count` | parse 超时次数 |
| `remote.not_allowed.count` | remote 因隐私策略未显式允许而被拒绝的次数 |
| `remote.fallback_to_local.count` | remote 失败后 fallback 到 local 的次数 |
| `parse_server.unavailable.count` | doclib 调用 parse-server 不可用次数 |
| `parse_server.failed.count` | doclib 调用 parse-server 失败次数 |
| `parse_server.local.start_failed.count` | managed 本地 parse-server 启动失败次数 |
| `parse.fallback.count` | 发生 fallback 的次数 |
| `parse.invalidate.count` | 用户或系统触发 invalidate 的次数 |
| `watch.error.count` | watch 主链路错误次数 |
| `parse.wait.timeout.count` | parse 同步等待超时次数 |
| `search.index.failed.count` | 搜索索引更新失败次数 |
| `doclib.content.render.failed.count` | 内容读取时渲染输出格式失败次数 |
| `parse.compaction.failed.count` | parse 批次 compaction 失败次数 |
| `cleanup.failed.count` | cleanup 失败次数 |

性能与规模分布:

| Metric | 说明 |
|--------|------|
| `ingest.file_size.bucket.count` | 入库文件大小分布 |
| `parse.duration.bucket.count` | parse 耗时分布 |
| `parse.queue.wait.duration.bucket.count` | parse 请求排队等待耗时分布 |
| `parse.page_count.bucket.count` | 单文件页数分布 |
| `parse.file_size.bucket.count` | 文件大小分布 |
| `parse_server.duration.bucket.count` | doclib 调用 parse-server 的耗时分布 |
| `doclib.content.render.duration.bucket.count` | 内容读取时渲染输出格式耗时分布 |
| `search.result_count.bucket.count` | search 返回结果数量分布，不采集 query 或结果内容 |
| `find.result_count.bucket.count` | find 返回结果数量分布，不采集 query 或结果内容 |
| `cleanup.requested.count` | cleanup 用户请求次数 |

Parse-server 相关 metric 必须带以下维度，便于区分用户是否使用 parse-server、使用哪类解析服务、以及对应 tier:

```text
server: local(managed) | local(self-hosted) | remote(official) | remote(custom) | unknown
tier: basic | standard | advanced | basic(default) | standard(default) | advanced(default) | unknown
status: succeeded | failed | partial | canceled
```

Parse-server 配置口径:

- `parse_server.configured.count`: 记录 doclib server 启动或 parse-server 配置变化时的配置状态。
- 本地 disabled 时，使用 `server=none`、`tier=unknown`。
- 本地 managed 时，使用 `server=local(managed)`、`tier=<managed tier>`。
- 本地 self-hosted 时，使用 `server=local(self-hosted)`、`tier` 来自能力发现结果；发现失败时为 `unknown`。
- 官方远端使用 `server=remote(official)`。
- 用户显式配置的其他远端兼容 parse-server 使用 `server=remote(custom)`。
- 不记录 remote URL。

本地 parse-server 的解析数量和性能通过以下查询口径获得:

- 数量: `parse_server.requested.count`、`parse_server.completed.count`、`parse_server.files.count`、`parse_server.processed_page_count`，且 `server=local(managed)` 或 `local(self-hosted)`。
- 性能: `parse_server.duration.bucket.count`，且 `server=local(managed)` 或 `local(self-hosted)`。
- 模式: 由 `server=local(managed)` 或 `local(self-hosted)` 区分。
- tier: `tier=basic`、`standard`、`advanced`、`basic(default)`、`standard(default)` 或 `advanced(default)`。

Telemetry 自身:

| Metric | 说明 |
|--------|------|
| `telemetry.enabled.count` | 用户开启 telemetry 次数 |
| `telemetry.disabled.count` | 用户关闭 telemetry 次数 |
| `telemetry.flush.succeeded.count` | telemetry 上报成功次数 |
| `telemetry.flush.failed.count` | telemetry 上报失败次数 |

## 12. P0 裁剪原则

P0 不一定实现所有候选 metric。裁剪时必须保留能回答以下问题的指标:

1. 使用规模: WAI、DAU、parse 次数、文件数、页数。
2. Agent 入口: `caller=agent` 与 `caller=user` 的使用差异。
3. 调用通道: HTTP API、SDK、CLI、MCP、Web、App、watch 和后台任务的来源分布。
4. 解析服务: 是否使用 parse-server，使用 `local(managed)`、`local(self-hosted)`、`remote(official)` 还是 `remote(custom)`，以及具体解析 tier。
5. 主链路质量: parse、ingest、render、search index 的成功和失败。
6. 关键性能: parse 耗时、parse-server 耗时、queue wait、render 耗时的 bucket。
7. 隐私边界: remote 是否被请求、允许、拒绝，以及 remote 失败后是否 fallback 到 local。

可优先裁剪或延后实现的指标:

- cleanup 和 compaction 维护类指标。
- server shutdown 等生命周期补充指标。
- continuation / truncation 等尚未进入第一版输出能力的指标。
- 过细且暂时没有 dashboard 消费场景的 bucket 指标。

## 13. Bucket 定义

耗时分桶:

```text
lt_1s | 1_5s | 5_30s | 30_120s | 2_10m | gt_10m
```

页数分桶:

```text
1 | 2_5 | 6_20 | 21_100 | 101_500 | gt_500
```

文件大小分桶:

```text
lt_1mb | 1_10mb | 10_50mb | 50_200mb | gt_200mb
```

search 结果数分桶:

```text
0 | 1_5 | 6_20 | 21_100 | gt_100
```

find 结果数分桶:

```text
0 | 1_5 | 6_20 | 21_100 | gt_100
```

## 14. 候选 Metric 口径

### 14.1 Ingest

Ingest 指文件进入 doclib 后计算 SHA256、提取基础 metadata、写入 `files` / `docs` / 文件名索引的阶段。

推荐维度:

```text
source: http_api | sdk | cli | mcp | web | app | watch | background | unknown
caller: agent | user | http_client | sdk | web | app | system | unknown
input_type
status
error_code
```

`ingest.duplicate.count` 表示同一 `sha256` 已存在，只新增或更新文件路径实例，不代表失败。

### 14.2 Search Index

Search index 指文件名索引和内容全文索引更新，不记录索引文本、snippet 或命中文档。

推荐维度:

```text
source: http_api | sdk | cli | mcp | web | app | watch | background | unknown
caller: agent | user | http_client | sdk | web | app | system | unknown
tier
status
error_code
```

`search.index.source_tier.count` 用于统计当前索引文本来自哪个 tier。搜索结果可以来自 `flash`，但用户主动阅读时不能默认停留在 `flash`。

### 14.3 Render / Content

Render 指 `GET /docs/{sha256}/content` 或等价 SDK/CLI 读取动作中，从 Middle JSON 转换为 Markdown、structured_content、HTML 等派生格式。

推荐维度:

```text
source
caller
output_format
tier
status
error_code
bucket
```

`doclib.content.requested.count` 记录内容读取请求。`doclib.content.rendered.count` 记录实际完成渲染。请求 `middle_json` 时可以只记录 requested，不一定记录 rendered。

### 14.4 Queue / Batch

Queue 和 batch 指 doclib parse 请求在 DB 任务队列中的创建、复用和等待行为。

推荐维度:

```text
source
caller
tier
status
```

`parse.created_batch.count` 表示请求创建了新的 parse batch。`parse.active_reused.count` 表示请求复用了已经存在的 pending/parsing batch。`parse.waited_batch.count` 表示当前请求需要等待的 batch 数；一次请求可以等待多个 batch。

`parse.queue.wait.duration.bucket.count` 只统计从请求进入等待到相关 batch 完成或失败的等待耗时，不包含实际 parse-server 执行耗时。

### 14.5 Remote Boundary

Remote metrics 只记录用户是否显式允许远端和是否发生 local fallback，不记录 remote URL、API Key 或账号信息。

推荐维度:

```text
source
caller
tier
status
error_code
```

`remote.requested.count` 表示当前请求显式带有 remote 语义。`remote.allowed.count` 表示隐私策略允许该请求使用 remote。`remote.not_allowed.count` 表示系统知道 remote 可能解决问题，但用户没有显式允许。`remote.fallback_to_local.count` 表示 remote 失败后按隐私边界 fallback 到 local。

### 14.6 Rules

Rules metrics 只记录规则是否命中，不记录 rule name、pattern、路径或文件名。

推荐维度:

```text
rule_type: exclude | parsing | unknown
tier
remote: true | false | unknown
```

`rules.excluded.count` 表示 exclude rule 阻止文件进入后续链路。`rules.parse_rule_applied.count` 表示 parsing-rule 决定了 tier、page_range 或 remote 语义。

### 14.7 Server Lifecycle

Server lifecycle metrics 记录 doclib server 和 managed local parse-server 的生命周期。

推荐维度:

```text
status
error_code
server
tier
```

`server.recovered_stale_lock.count` 用于统计启动恢复能力。`parse_server.local.start_failed.count` 和 `parse_server.local.restarted.count` 用于观察 managed local parse-server 稳定性。

### 14.8 Compaction / Cleanup

Compaction 和 cleanup 属于维护链路，用于观察 JSON 批次增长、孤儿记录和文件清理效果。

推荐维度:

```text
tier
status
error_code
```

这些指标不记录 sha256、路径或文件名。

### 14.9 CLI 行为

CLI 行为 metrics 只记录用户或 Agent 使用了哪些 `mineru` 子命令和关键模式，不记录命令参数中的路径、query、pattern、URL、API Key 或输出内容。

推荐维度:

```text
source: cli
caller
command
status
```

`cli.command.count` 的 `command` 取值:

```text
parse | invalidate | search | find | show | cleanup | server | config | telemetry | unknown
```

`server.command.count` 的 `command` 取值:

```text
start | stop | restart | status | unknown
```

`GET /server/status` 不计入 `server.command.count`，避免健康检查和轮询污染。只有用户或 Agent 通过 CLI 主动执行 `mineru server status` 时才记录。

Parse CLI 行为推荐维度:

```text
source: cli
caller
tier
server
output_format
wait_mode
wait_bucket
page_range_mode
status
```

口径:

- `parse.output.requested.count`: 记录 `--format` 请求的输出格式。
- `parse.output.to_stdout.count`: 输出到 STDOUT。
- `parse.output.to_file.count`: 指定 `--output` 写入文件；不记录输出路径。
- `parse.marker.disabled.count`: 用户传入 `--no-marker`。
- `parse.wait_mode.count`: `--no-wait` 记为 `wait_mode=async`，否则记为 `sync`。
- `parse.wait.timeout.count`: 同步等待超时。
- `parse.page_range.requested.count`: 未传页码为 `default`，显式 `all` 为 `all`，其他页码范围为 `partial`；不记录具体页码字符串。
- `parse.force.count`: 用户传入 `--force`。

配置类 CLI 行为推荐维度:

```text
source: cli
caller
config_area
server
tier
remote
status
```

口径:

- `config.watch.added.count` / `config.watch.removed.count`: 不记录 watch path、label 或 removable 设备标识。
- `config.rule.added.count` / `config.rule.removed.count`: 不记录 rule name、pattern 或 page_range。
- `config.parse_server.changed.count`: 不记录 URL 或 API Key，只通过 `server` 区分 `local(managed)`、`local(self-hosted)`、`remote(official)`、`remote(custom)`、`none`、`unknown`。

Cleanup CLI 行为推荐维度:

```text
source: cli
caller
cleanup_target
dry_run
status
```

`cleanup_target` 取值:

```text
orphan_docs | deleted_files | temp | mixed | unknown
```

## 15. Doclib API 感知范围

Telemetry 不记录所有 doclib HTTP API 调用，只记录能够代表产品使用规模或核心行为的 API。

对用户行为类 API，调用方应尽量向 doclib 传递 `caller`。这使 telemetry 可以区分 Agent 调用 `mineru` 命令和用户直接调用 `mineru` 命令。不能可靠识别时使用 `unknown`，不得通过敏感内容推断。
直接调用 HTTP API 且未传 caller 信息时，`source=http_api`、`caller=http_client`。SDK、CLI、MCP、Web 和桌面 App 应由对应入口向 doclib 传递 `source` 与 `caller`。

应记录的 API:

| API | Metric | 说明 |
|-----|--------|------|
| `POST /parses` | `parse.requested.count` 等 parse 指标；使用 parse-server 时记录 `parse_server.*` 指标 | 记录请求、cache hit/miss、完成/失败、文件数、页数、tier、耗时、大小分布和 parse-server 使用情况 |
| `POST /invalidate` | `parse.invalidate.count` | 记录 invalidate 行为，不记录路径或 sha256 |
| `GET /search` | `search.performed.count`、`search.result_count.bucket.count` | 不记录 query、命中文档或返回内容 |
| `GET /find` | `find.performed.count`、`find.result_count.bucket.count` | 与 search 分开统计，不记录 query、命中文档或返回内容 |
| `GET /docs/{sha256}/content` | `doclib.content.requested.count` | 记录内容读取或渲染次数，不记录 sha256 或内容 |

不应记录为 telemetry 的 API:

| API | 原因 |
|-----|------|
| `GET /parses` | 状态查询和轮询噪音较大 |
| `GET /parses/{id}` | 状态查询，不代表核心产品使用量 |
| `GET /docs` | 列表浏览噪音较大 |
| `GET /docs/{sha256}` | 元数据读取，P0 不作为核心指标 |
| `GET /files/by-path` | 工具性查询 |
| `GET /config` / `POST /config` | 普通配置读取和修改不计入，telemetry 开关变化除外 |
| watch / rules 配置 API | 只记录后台 watch 实际发现和解析行为 |
| cleanup API | 管理维护行为 |
| `GET /server/status` | 健康检查和轮询会污染活跃度 |
| `POST /shutdown` | 管理行为 |

## 16. 本地存储

Telemetry 用户状态、内部状态和聚合数据都存储在 doclib DB 中，不使用启动前文件配置。

Telemetry endpoint 不支持用户配置，应由代码内置。开发和测试环境如需覆盖 endpoint，应使用测试构建或专门的开发开关，不进入用户配置体系。

建议状态结构可以继续用 KV 表表达:

```toml
[telemetry]
consent_state = "enabled"
installation_id = "inst_01HX..."
last_flush_at = "2026-06-10T12:00:00Z"
```

状态语义:

- `consent_state`: 用户 telemetry 状态，取值为 `unset` / `enabled` / `disabled`。
- `installation_id`: 内部匿名安装实例 ID，用户不可配置，也不需要默认展示完整值。
- `last_flush_at`: 内部运行状态，表示最近一次成功 flush 时间，不是用户配置。

`consent_state` 语义:

| 值 | 含义 |
|----|------|
| `unset` | 用户尚未完成首次选择，doclib server 应展示或触发首次选择流程 |
| `enabled` | 用户允许记录并上报 telemetry |
| `disabled` | 用户明确关闭 telemetry |

如果 `consent_state=disabled`，doclib server 不应写入新的 telemetry 聚合数据。

Telemetry 聚合数据应使用独立表保存，至少包含:

| 字段 | 说明 |
|------|------|
| `id` | 本地聚合记录 ID |
| `period_start` | 聚合窗口开始时间 |
| `period_end` | 聚合窗口结束时间 |
| `metric_name` | metric 名称 |
| `metric_value` | 非负数值 |
| `dimensions` | metric-level dimensions JSON |
| `dimensions_hash` | dimensions JSON 的稳定 hash，用于聚合 upsert |
| `created_at` | 创建时间 |
| `updated_at` | 最近更新时间 |

聚合唯一键:

```text
period_start + period_end + metric_name + dimensions_hash
```

同一唯一键重复写入时，累加 `metric_value`。聚合 key 不包含 context；flush 时读取当前 context 并组装 telemetry batch。服务端确认成功接收后，删除对应聚合记录。网络失败或 5xx 时保留记录以便后续重试。

Flush 并发与幂等采用 P0 简单方案:

1. doclib 同一时间只允许一个 flush 任务执行。
2. flush 开始时获取本地 flush lock；已有 lock 且未过期时，本次 flush 直接跳过。
3. flush 从 DB 读取一批未上报聚合记录，生成 `batch_id` 并 POST 到 telemetry endpoint。
4. 服务端确认成功接收后，本地删除这些聚合记录。
5. 如果 POST 成功但本地删除前 doclib 崩溃，后续可能重复上报同一批 metrics。
6. P0 接受少量重复。服务端应基于 `batch_id` 在短窗口内做幂等去重；超过窗口的重复数据由 cleaned metrics 层处理。

Flush lock 可以放在 telemetry 内部状态中，例如:

```toml
[telemetry]
flush_locked_at = "2026-06-10T12:00:00Z"
```

## 17. 服务端防污染

匿名 telemetry endpoint 无法完全避免伪造数据。服务端必须把本地 telemetry 视为半可信数据，只用于趋势分析。

服务端必须实现:

- schema version 校验
- metric name 白名单
- context key/value 白名单
- dimension key/value 白名单
- `value` 非负数校验
- batch 大小限制
- period 时间范围限制
- `installation_id` 限流
- IP 限流
- 异常数据 quarantine
- raw metrics 与 cleaned metrics 分层

Dashboard 默认展示 cleaned metrics。mineru.net API 服务端日志属于 trusted usage，本地 anonymous telemetry 属于 anonymous product analytics，两类数据必须分开标记和分析。

## 18. P0 实现边界

P0 需要完成:

- doclib server telemetry DB 配置读取与首次选择状态管理。
- 匿名 `installation_id` 生成并持久化到 doclib DB。
- telemetry metrics 聚合存储到 doclib DB。
- 小时级 period 聚合与 metric upsert。
- flush 成功后删除 DB 中已确认上报的 telemetry 聚合数据。
- `mineru` CLI、Doclib SDK、MCP、Web、桌面 App 和直接 HTTP API 到 doclib server 的 `source` / `caller` 透传。
- P0 metric 白名单与 dimension 白名单。
- 周期 flush 与失败重试。
- `mineru telemetry status|enable|disable|preview|flush`。
- 服务端 endpoint schema。

P0 不需要完成:

- 每事件实时上报。
- 详细硬件画像。
- 账号级归因。
- GPU 型号、显存、驱动和 CUDA 版本采集。
- exception message / traceback 上报。
- telemetry 结果查询 API。