Telemetry 设计¶
状态: Superseded
取代说明: 本文已被 telemetry-minimum.md 全面取代,仅保留历史设计参考;现状以 telemetry-minimum.md 与代码为准。
读者: 产品负责人、核心开发者、doclib server 开发者、数据分析与合规参与者
范围: 下一代 MinerU 的匿名使用统计、稳定性指标和粗粒度环境画像
非目标: 计费、审计、安全风控、精确故障追踪、上传文档内容或用户输入
1. 目标¶
Telemetry 的首要目标是产品使用统计,用于评估 MinerU 的使用规模和产品影响力。
P0 同时兼顾三类问题:
- 产品使用统计: 有多少安装实例在使用、每天使用多少次、处理了多少文件和页面。
- 质量与稳定性: 哪些主链路失败、失败发生在哪个阶段、错误码分布如何。
- 性能与环境画像: 不采集细粒度设备指纹,只用粗粒度字段理解运行环境和处理规模。
Telemetry 数据只用于趋势分析和产品改进,不用于计费、安全判断或强一致审计。
2. 采集边界¶
只有 doclib server 上报 telemetry。
mineru CLI 依赖 doclib server,因此可以被间接统计。以下纯工具无 telemetry 能力:
- parser SDK,包括
mineru.parser.parse()和parse_async() mineru-kit parsemineru-kit api-server- 其他不依赖 doclib server 的专家工具
这个边界避免 parser/tool 层在作为库或底层工具使用时包含 telemetry 相关配置、存储或网络行为。
3. 默认策略¶
首次启动 doclib server 时,必须要求用户完成 telemetry 选择。
默认行为:
- 首次选择界面不预选开启或关闭。
- 用户可以关闭。
- 用户选择结果记录为
consent_state。 - 用户关闭 telemetry 后,不再记录新的 telemetry metrics,也不再上报。
- 关闭时,DB 中未上报 telemetry 数据应删除,避免后续误发。
用户必须可以通过命令查看和修改状态:
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 上报,不采用每个事件即时上报。
运行时行为:
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:
不建议与 mineru.net/api 的 parse API 混在一起,因为 telemetry 的认证、限流、存储和合规策略不同。
响应示例:
{
"object": "telemetry_metrics_result",
"accepted": 42,
"rejected": 0,
"server_time": "2026-06-10T12:00:00Z"
}
如果服务端支持部分拒绝,可以返回:
{
"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。
{
"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:
{
"name": "parse.completed.count",
"value": 1,
"dimensions": {
"tier": "basic",
"status": "succeeded"
}
}
不允许:
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:
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。裁剪时必须保留能回答以下问题的指标:
- 使用规模: WAI、DAU、parse 次数、文件数、页数。
- Agent 入口:
caller=agent与caller=user的使用差异。 - 调用通道: HTTP API、SDK、CLI、MCP、Web、App、watch 和后台任务的来源分布。
- 解析服务: 是否使用 parse-server,使用
local(managed)、local(self-hosted)、remote(official)还是remote(custom),以及具体解析 tier。 - 主链路质量: parse、ingest、render、search index 的成功和失败。
- 关键性能: parse 耗时、parse-server 耗时、queue wait、render 耗时的 bucket。
- 隐私边界: remote 是否被请求、允许、拒绝,以及 remote 失败后是否 fallback 到 local。
可优先裁剪或延后实现的指标:
- cleanup 和 compaction 维护类指标。
- server shutdown 等生命周期补充指标。
- continuation / truncation 等尚未进入第一版输出能力的指标。
- 过细且暂时没有 dashboard 消费场景的 bucket 指标。
13. Bucket 定义¶
耗时分桶:
页数分桶:
文件大小分桶:
search 结果数分桶:
find 结果数分桶:
14. 候选 Metric 口径¶
14.1 Ingest¶
Ingest 指文件进入 doclib 后计算 SHA256、提取基础 metadata、写入 files / docs / 文件名索引的阶段。
推荐维度:
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 或命中文档。
推荐维度:
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 等派生格式。
推荐维度:
doclib.content.requested.count 记录内容读取请求。doclib.content.rendered.count 记录实际完成渲染。请求 middle_json 时可以只记录 requested,不一定记录 rendered。
14.4 Queue / Batch¶
Queue 和 batch 指 doclib parse 请求在 DB 任务队列中的创建、复用和等待行为。
推荐维度:
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 或账号信息。
推荐维度:
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、路径或文件名。
推荐维度:
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 的生命周期。
推荐维度:
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 批次增长、孤儿记录和文件清理效果。
推荐维度:
这些指标不记录 sha256、路径或文件名。
14.9 CLI 行为¶
CLI 行为 metrics 只记录用户或 Agent 使用了哪些 mineru 子命令和关键模式,不记录命令参数中的路径、query、pattern、URL、API Key 或输出内容。
推荐维度:
cli.command.count 的 command 取值:
server.command.count 的 command 取值:
GET /server/status 不计入 server.command.count,避免健康检查和轮询污染。只有用户或 Agent 通过 CLI 主动执行 mineru server status 时才记录。
Parse CLI 行为推荐维度:
口径:
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 行为推荐维度:
口径:
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 行为推荐维度:
cleanup_target 取值:
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 表表达:
[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 |
最近更新时间 |
聚合唯一键:
同一唯一键重复写入时,累加 metric_value。聚合 key 不包含 context;flush 时读取当前 context 并组装 telemetry batch。服务端确认成功接收后,删除对应聚合记录。网络失败或 5xx 时保留记录以便后续重试。
Flush 并发与幂等采用 P0 简单方案:
- doclib 同一时间只允许一个 flush 任务执行。
- flush 开始时获取本地 flush lock;已有 lock 且未过期时,本次 flush 直接跳过。
- flush 从 DB 读取一批未上报聚合记录,生成
batch_id并 POST 到 telemetry endpoint。 - 服务端确认成功接收后,本地删除这些聚合记录。
- 如果 POST 成功但本地删除前 doclib 崩溃,后续可能重复上报同一批 metrics。
- P0 接受少量重复。服务端应基于
batch_id在短窗口内做幂等去重;超过窗口的重复数据由 cleaned metrics 层处理。
Flush lock 可以放在 telemetry 内部状态中,例如:
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 聚合数据。
mineruCLI、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。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU