言录：结构化日志

言录（yanxu-log）1.0.0 把日志记录、格式化和输出处理分开，提供稳定记录模式 v1、六级日志、上下文、递归脱敏、采样、容错处理器和请求/数据库字段构造器。只有文件处理器会使用包清单声明的文件能力。

版本与安装

yanbao add 言录 \
  --git https://github.com/yanxulang/yanxu-log.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言录 = { git = "https://github.com/yanxulang/yanxu-log.git", 修订 = "v1.0.0", 版 = "^1.0" }

言录自身的清单把言据固定为公开 v1.2.0 标签。应用应提交 言序.lock，继续固定完整依赖图、修订和内容校验。

核心能力：创建日志器

引「包:言录」为 言录；

定 文件器 为 言录.JSON文件处理器（
    「logs/应用.jsonl」，
    言录.信息级，
    10485760，
    5
）；

定 日志 为 言录.日志器（
    言录.追踪级，
    「订单服务」，
    「HTTP」，
    【言录.控制台处理器（言录.调试级），文件器】，
    {「环境」：「生产」}
）；

日志.子日志器（「创建订单」，{「请求号」：「r-42」}）
    .信息于（「创建成功」，{
        「订单号」：「o-1」，
        「Authorization」：「Bearer secret」
    }）；

每条记录包含模式版本、时间戳、等级、等级值、消息、模块、频道、字段和可选错误。上下文与输入会深复制；处理器和采样器各自收到隔离副本，不能通过修改参数污染最终记录。

等级、上下文与错误

每一级都有纯消息入口和带字段入口，例如 信息与信息于。低于日志器最低等级的调用直接返回空，不创建记录，也不推进采样器。

定 请求日志 为 日志
    .子日志器（「创建账户」，{「请求号」：「r-42」}）
    .频道（「业务」）
    .上下文（{「追踪号」：「trace-7」}）；

试 则
    执行业务（）；
救 所误 则
    请求日志.记错误（「执行失败」，所误，{「订单号」：「o-1」}）；
终

记错误保留言序错误的代码、类别、消息、位置和踪迹；不要只记录消息而丢失诊断，也不要把未过滤的完整错误详情直接返回给客户端。

脱敏与采样

默认敏感键覆盖常见中英文密码、令牌、认证首部、Cookie、API Key、客户端密钥、DSN 和连接串，按大小写不敏感匹配并递归处理列与典：

日志.设脱敏（
    【「密码」，「访问令牌」，「Authorization」】，
    「[已隐藏]」
）；

日志.固定采样（10，言录.警告级）；

固定间隔采样器保留每个周期的第一条低等级记录，并始终保留达到保护等级的记录。也可用 固定间隔采样器和设采样器显式管理计数，或提供实现 保留(记录):理的自定义采样器。

脱敏只按结构化键工作，不扫描消息、错误消息或 SQL 模板。凭据必须放在可脱敏字段中，不能先拼入自由文本。

处理器

文件轮转阈值按 UTF-8 字节计算。下一条完整记录会越过阈值时，当前文件备份为 .1，旧备份依次推进到 .N；单条记录不会拆开，但仍受 1 MiB 单条预算约束。轮转字节=0关闭轮转，保留份数=0表示轮转时只清空当前文件。

默认情况下处理器错误向调用方传播。只应把容错处理器用于可以丢失的遥测输出；主审计日志故障不应被静默掩盖。

请求与数据库日志

日志.记请求（
    「请求完成」，「POST」，「/orders?token=secret」，201，18，
    {「Authorization」：「Bearer secret」}，
    {「请求号」：「req-1」}
）；

日志.记数据库（
    「查询完成」，「PostgreSQL」，「查询」，
    「SELECT id FROM orders WHERE id = $1」，7，1，
    {「id」：42}，{「事务号」：「tx-1」}
）；

请求字段会移除查询和片段；绝对 HTTP 地址还会移除整个权限部分。数据库字段把 SQL 模板和参数分开，并递归脱敏参数与扩展字段。调用方仍应传路由模板和参数化 SQL，不记录正文、完整 Cookie、连接地址或拼接后的 SQL。

权限与安全边界

最终清单声明：

[权限]
文件 = ["."]
网络 = []
TCP监听 = []
UDP绑定 = []
环境 = []
进程 = false
原生扩展 = false

文件权限服务于显式启用的文件处理器；只用内存、控制台或函数处理器时，运行路径不会访问文件。顶层应用仍应只授权专用日志目录，不能让不可信输入决定路径。言录不创建父目录，也不管理目录权限。

消息、名称、字段容器、嵌套深度、处理器数、内存记录、单条字节数、路径和轮转配置都有硬上限；超限使用稳定 YANLU_错误。捕获后调用 错误详情并按代码分支，不要解析中文消息。

已知限制

• 默认脱敏不是数据防泄漏扫描器，无法清除已经进入消息、错误文字或 SQL 模板的秘密。
• 内置轮转不是原子事务，也没有跨进程锁；一个路径只应由一个进程写入，不适合作为不可丢失或追加证明的审计存储。
• 文件路径、符号链接、挂载点、只读权限和文件占用遵循宿主操作系统行为。
• 控制台展示文字、错误踪迹布局和典的调试顺序不是跨版本机器协议；机器消费应使用记录模式 v1、JSON Lines 或言据结构。
• 自定义格式化器、写出器、采样器和时间源是受信回调，其资源消耗及顶层权限由应用负责。

项目链接

• GitHub 仓库
• 言录 1.0.0 Release