db + ingest-otlp：存数据库 + 接入 OTLP

repeated analyze 慢 —— 30 天窗口里 200 个 session、每个 JSONL 几 MB，重 parse 就是「每次跑都要等几秒」。需要一个持久化层把 parse 结果固化，下次跨 session 查询直接走 SQLite index，毫秒级响应。

agentprof db 是 6 个子命令的家族：

• init —— 在指定路径建空 store（schema migration 自动跑）
• ingest —— 批量把 adapter 输出的 sessions 写进 store
• stats —— 看 store 当前大小 / session 数 / 最早最晚时间
• prune --since 30d —— 按时间窗口删除老 session（释放空间）
• vacuum —— SQLite VACUUM 整理碎片
• export —— 把 store 内容导出成 JSONL（迁移 / 备份）

配合 hybrid mode（见下一张卡片），dev 端基本不用动 store；CI / 团队场景才显式 init。

直接走 Adapter 不开 cache（--no-cache）—— 每次重 parse，适合「跑完即弃」的一次性诊断；或者「怀疑 cache 损坏」想强制重读 source-of-truth 的场景。生产 / 长期 trend 场景几乎总是要 store。

一句话决策：dev 本地 → cache（不用管，自动开）；CI / 团队 / 长期 trend / OTLP push → store（显式 --storage-path）。两者 schema 完全相同，从 cache 升级到 store 不需要数据迁移：重新 analyze --storage-mode store 即可，旧 cache 文件可保留也可删。

默认就是 cache，啥都不用做。想用 store：

agentprof db init --storage-path ~/.local/share/agentprof/store.sqlite
agentprof analyze --storage-mode store   # 后续命令显式带 --storage-mode store

也可以写进 ~/.config/agentprof/config.toml 一劳永逸：

[storage]
mode = "store"
path = "~/.local/share/agentprof/store.sqlite"

Cache：$XDG_CACHE_HOME/agentprof/cache.sqlite（默认 ~/.cache/agentprof/，OS 可以随时清，agentprof 容忍丢）
Store：$XDG_DATA_HOME/agentprof/store.sqlite（默认 ~/.local/share/agentprof/，用户拥有，agentprof 不主动动）。
OTLP receiver 写当前 mode 对应的单一 storage，由 --storage-mode / --storage-path 决定，默认 cache。

完整设计决策（XDG 命名背后的取舍 / dual-path read fan-out / dual-write 为何被否决）在 Wiki §5 「存储层 hybrid mode」详述，本课只覆盖「用户怎么选」。简短回答：cache 是「性能优化」，store 是「业务数据」，两者职责清晰不混 —— 见 ADR-0019。

file-based 模式（read JSONL）只覆盖 Copilot CLI / 老 Claude 这类「写日志到磁盘」的 agent。Claude Code（新版）/ Codex 用 OTel SDK 是 native —— 它们已经会发 spans，agentprof 只需要在另一头听就行，不用让 agent 团队额外写「导出 events.jsonl」逻辑。

# gRPC（默认，性能最好）
agentprof ingest-otlp --bind 127.0.0.1:4317 \
  --storage-path ~/.local/share/agentprof/store.sqlite

# HTTP/protobuf（防火墙穿透更友好）
agentprof ingest-otlp --bind 127.0.0.1:4318 --protocol http \
  --storage-path ~/.local/share/agentprof/store.sqlite

# 想加 bearer auth（生产建议）
agentprof ingest-otlp --bind 0.0.0.0:4317 \
  --auth-token-file ~/.config/agentprof/otlp-bearer.txt \
  --tls-cert ./server.pem --tls-key ./server.key

需要编译时开 otlp feature（拉 workspace dep tonic + prost + axum）。full 默认含。

Claude Code / Codex SDK 都遵循 OTel 标准环境变量协议：

# Bash / zsh（gRPC 默认）
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_SERVICE_NAME=claude-code
# 可选：bearer auth
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $(cat ~/.config/agentprof/otlp-bearer.txt)"

# 之后跑 agent，spans 自动 push 到 agentprof
claude code "your task"

⚠️ Claude Code 当前 v1.x 通过 OTEL_* 环境变量配 OTLP。如果你跑的是自家 agent / 用了 OTel collector 链路（agent → collector → agentprof），collector 端把 agentprof 作为 exporter：

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  otlp/agentprof:
    endpoint: 127.0.0.1:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/agentprof]

详见 ADR-0022：Bearer 常时间比较（防时序攻击）/ 每信号大小上限 8/2/8 MiB（防 OOM）/ LRU eviction 1024 sessions（防内存撑爆）/ session.id 256-byte 上限（防 path injection）。

# 验证 receiver 在线
curl -v http://127.0.0.1:4318/v1/traces -X POST   # 期望 415 (no protobuf body)

# 看进了多少 session
agentprof db stats --storage-path ~/.local/share/agentprof/store.sqlite

# 看实时 receiver 日志
RUST_LOG=agentprof_storage::otlp=debug agentprof ingest-otlp ...

自建 OTel Collector + ETL 到 agentprof —— 技术上行，但多一层进程 + 多一套配置，单机 / 小团队不值得。agentprof 内置 OTLP receiver 已够覆盖「5–50 个 dev 同时推」量级；超过这个量级再上正经 collector。