本地遥测
了解本地遥测
Section titled “了解本地遥测”Marivo 会按 UTC 日期把采用开放遥测结构的本地 JSONL 事件写入项目状态目录：
.marivo/telemetry/events-2026-07-29.000.jsonl末尾三位数字是大小分片编号。当前文件继续写入后将超过 128 MiB 时，Marivo 会创建下一个 分片。多个进程并发追加时，该大小限制为近似上限。
Marivo 保留 14 个 UTC 日历日内的受管事件文件。每个 UTC 日首次写入时，还会从最旧的历史
分片开始清理，直到历史遥测不超过 1 GiB；清理不会删除当前 UTC 日的文件。旧版本
留下的 .marivo/telemetry/events.jsonl 不会被自动处理。确认其中的事件不再需要后，应
显式归档或删除该文件。
遥测结构 v2 覆盖显式调用的 CLI、数据源、语义和分析公开操作。 每次操作会写入一对可关联事件：
marivo.operation.startedmarivo.operation.completed
两条事件共享操作 ID。嵌套的公开调用还会记录 parent 操作 ID；完成事件包含
状态、总耗时、稳定的结构化错误与修复字段，或者有界的结果摘要。耗时较高的操作还可能
记录验证、执行、持久化和证据阶段耗时。
marivo.operation.origin 属性用于区分顶层 explicit 调用、delegated 委托调用和
语义 internal_load 期间执行的声明。恢复已有分析会话并重新加载语义
目录时，成功的内部声明不会重复写入；外层语义 load 和失败的声明仍会保留。
带会话的事件可以包含持久化的 session.question。分析操作会在调用方传入时记录
analysis_purpose，md.raw_sql(...) 会记录其必填的 reason。创建或恢复会话时，
事件还会说明本次传入的问题是否真正生效，还是因为恢复已有会话而被忽略。
输入摘要可以包含规范化的指标、维度、数据源、语义和产物标识符，
以及计数、类型、选项、限制和指纹。对于约束、数据源 client tags 等
未定义为规范标识符集合的字符串集合，只记录数量和元素类型。show()、contract()、
to_pandas() 等显式读取会记录 receiver 产物/引用和 producing job，用于把产物与后续
消费关联起来。结果摘要可以包含产物/job 标识符、内容 hash、结果类型与状态、
行数、问题数、缓存状态、截断状态和证据状态。遥测永远不会记录凭据、解析后
的密钥、数据源主机、DSN、SQL 原文、文件路径、slice 实际值、frame 行值、自由文本
集合元素、任意对象 repr 或异常消息。
升级后，旧的 events.jsonl 中可能仍保留结构 v1 行，Marivo 不会迁移该文件。需要读取
历史数据的消费者应扫描按日期命名的 events-*.jsonl，并在需要时单独读取旧文件；同时应
筛选 marivo.event.schema_version 属性为 2 的记录。
这些事件只保存在本地，Marivo 不会上传它们。会话问题、分析目的和原始-SQL reason 会以原文保存在本地事件文件中；在把项目状态分享给其他环境之前应先检查该文件。
通过环境变量为当前进程关闭本地遥测：
MARIVO_TELEMETRY=off marivo init也可以在 marivo.toml 中设置项目默认值：
[telemetry]enabled = "off" # "on" 或 "off"MARIVO_TELEMETRY=on|off 会覆盖当前进程的 [telemetry].enabled 设置。两者均未设置时，
本地遥测默认使用 "on"。