本文说明 BinlogViz 的产品边界，帮助运维人员理解这个工具被设计成做什么，以及它刻意不做什么。
BinlogViz 面向本地 MySQL ROW 格式 binlog 文件。
这个边界非常重要，因为分析器的设计前提是消费规范化后的行级事件，并从行级写入活动中推导负载统计。如果你的运维问题依赖 statement-based replay 语义，那么应该选择另一类工具链。
换句话说，当你的输入是本地 ROW 格式 binlog 序列，并且目标是做负载分析而不是逻辑回放时，BinlogViz 才是合适的工具。
BinlogViz 只分析本地文件。
命令只接受两种输入方式之一：
- 显式位置参数 binlog 路径
- 使用
--from-dir加--prefix的 discovery 模式
它不会帮你拉取远程 binlog，也不会连接在线 MySQL 实例，更不会替你管理复制位点。discovery 模式本身也被刻意限定为窄契约：扫描单个目录、按前缀加纯数字后缀过滤，再把结果排序后送去分析。
这种设计让输入契约保持可预测，但也意味着运维人员需要先把本地文件集准备好。
BinlogViz 采用单次流式命令路径：
parse -> normalize -> consume -> finalize -> render
这个设计让运行过程中的常驻内存状态保持有界，但并不意味着分析在命令末尾没有成本。
几个重要的运行时影响：
- 解析阶段是流式的
- 最终报告组装仍然发生在解析完成之后
- 使用
--detail-store duckdb时每次命令都会创建一个临时 DuckDB 存储（默认：none） - 输入越大，finalize 阶段越可能表现出明显耗时和临时磁盘占用
因此，这个产品优化的是有界流式分析，而不是零磁盘、也不是完全增量式的交互探索。
SQL 上下文是有界的，而且面向展示。
当前限制包括：
- 存储 SQL 最大
4096字节 - 查询摘要最大
160个字符 - 查询字段是否展示由
--sql-context控制
这意味着：
- BinlogViz 不承诺无损保存原始 SQL 文本
summary模式用于帮助运维快速建立判断上下文- 即便是
full模式，也只会暴露有界存储后的 SQL，而不是无限长度的原始语句
如果你的流程需要完整长 SQL 的归档或取证保存，就不应把 BinlogViz 当作那个系统。
BinlogViz 有意把输出通道分离：
- 最终报告写到
stdout - 进度、解析出的文件列表、finalize 状态以及命令错误写到
stderr
这个契约便于 shell 重定向和自动化，但也意味着运维人员不应把 stderr 内容误当成报告载荷的一部分。如果你只重定向 stdout，得到的是报告；如果你也想保留运行状态日志，就要单独捕获 stderr。
BinlogViz 聚焦于负载分析，而不是完整的数据库运维控制面。
它被设计来回答的问题包括：
- 哪些表最热
- 哪些事务最大
- 什么时候出现活动尖峰
- 整体写入负载长什么样
它并不定位为：
- MySQL 复制管理器
- 实时 binlog tailing 服务
- statement replay 引擎
- 完整历史数据重建工具
- 通用 SQL 可观测性平台
为了保持产品聚焦，以下内容是当前文档范围内的明确非目标：
- 管理或修改 MySQL 服务器状态
- 在分析过程中直接连接远程 MySQL 实例读取数据
- 在报告中无限制保存原始 SQL 文本
- 将进度输出并入机器可读报告流
- 替代更深入的复制、取证或可观测性系统
当你需要的是本地 ROW binlog 工作负载的快速运维总结时，使用 BinlogViz。若你需要远程采集、statement 级精确重建，或更广泛的数据库运维平台，则应该选择其他工具。