开放接口调用记录至少要覆盖五类信息：调用标识与时间、调用方身份、接口与参数、结果与错误、链路与审计。字段取舍取决于记录要支撑排障、审计、计量还是追责，先定用途再定字段，能避免全量堆砌带来的存储与检索负担。本文给出一份可直接套用的字段清单，并说明采集、保留、角色分工与上线验收的做法。
要点总览（TL;DR）
- 调用记录按排障、审计、计量、追责四类用途反推字段，分必备与按需两层，避免全量堆砌。
- 必备字段覆盖五类：请求ID与调用时间、调用方身份、接口方法与版本、状态码与错误信息、来源IP与追踪ID。
- 凭证、Token、密码类参数只留标识或哈希，请求体响应体按需截断并标注截断标记。
- 采集以网关统一采集为基础，应用内埋点补充业务上下文，两侧统一字段命名与追踪ID规则。
- 上线前抽查字段完整性、验证脱敏与权限、用追踪ID串联日志、确认保留与清理任务按计划执行。
一份调用记录要回答哪几个问题
调用记录的价值在于事后能还原“谁、在什么时候、通过什么接口、做了什么、结果如何”。围绕这个还原过程，记录通常要支撑四类用途，每类用途对字段的要求不同。
| 用途 | 要回答的问题 | 关键字段 | 记录侧重点 |
|---|---|---|---|
| 排障 | 这次调用为什么失败，问题出在调用方还是接口侧 | 请求ID、调用时间、耗时、接口方法路径、状态码、错误码、错误信息、追踪ID | 时间精度、错误细节、上下游关联 |
| 审计 | 谁在什么时间调用了哪个接口，是否越权 | 调用方应用、凭证标识、操作人、来源IP、接口版本、访问结果 | 身份可追溯、记录不可篡改 |
| 计量 | 某个应用或某个接口被调用了多少次、消耗多少资源 | 调用方应用、接口标识、调用时间、响应大小、耗时 | 可聚合、字段口径统一 |
| 追责 | 异常调用由谁发起，是否按约定使用 | 调用方身份、操作人、关键参数摘要、关联业务对象、追踪ID | 身份与业务对象可关联 |
按用途反推字段后，再把字段分成两层：必备层是任何一次调用都要落下的基础信息，缺了就无法完成最基本的排障和审计；按需层根据接口敏感程度、业务重要性和合规要求补充，例如关键参数摘要、响应大小、关联业务对象。这样既保证底线，又避免为低频场景付出全量存储成本。
必备字段清单与填写口径
下表给出可直接落地的字段清单。字段名可按团队命名习惯调整，取值口径和脱敏要求建议在字段规范中固定下来，避免不同采集点各写各的。
| 类别 | 字段名 | 类型 | 示例 | 是否必填 | 脱敏/处理方式 |
|---|---|---|---|---|---|
| 调用标识与时间 | request_id | 字符串 | req-20240612-8f3a2c | 必填 | 原样保留，需全局唯一 |
| 调用标识与时间 | called_at | 时间戳 | 2024-06-12T10:23:41.512+08:00 | 必填 | 统一时区与精度（毫秒） |
| 调用标识与时间 | duration_ms | 整数 | 187 | 必填 | 原样保留 |
| 调用方身份 | app_id | 字符串 | crm-sync | 必填 | 原样保留 |
| 调用方身份 | credential_id | 字符串 | ak-9d2e（后四位掩码） | 必填 | 凭证只留标识，不留密钥原文 |
| 调用方身份 | operator | 字符串 | zhangsan | 按需 | 用户标识可保留，手机号等掩码 |
| 接口与参数 | http_method | 字符串 | POST | 必填 | 原样保留 |
| 接口与参数 | path | 字符串 | /open/v2/issues | 必填 | 原样保留，含版本段 |
| 接口与参数 | api_version | 字符串 | v2 | 必填 | 原样保留 |
| 接口与参数 | param_digest | 字符串 | project=42;type=bug | 按需 | 只记关键参数摘要，敏感值掩码 |
| 结果与错误 | status_code | 整数 | 400 | 必填 | 原样保留 |
| 结果与错误 | biz_code | 字符串 | INVALID_PARAM | 必填 | 原样保留 |
| 结果与错误 | error_message | 字符串 | 字段 type 取值非法 | 必填 | 截断至约定长度，避免写入敏感内容 |
| 链路与审计 | source_ip | 字符串 | 10.12.3.45 | 必填 | 内网可原样，公网按合规要求处理 |
| 链路与审计 | trace_id | 字符串 | trace-7c1b90 | 必填 | 原样保留，用于串联上下游 |
| 链路与审计 | business_ref | 字符串 | issue#10231 | 按需 | 只记业务对象标识 |
脱敏与截断规则需要在字段规范中写清楚，常见做法有三条。请求头中的凭证、Token、密码类参数一律不落原文，只保留凭证标识或哈希值；请求体与响应体按需记录时设置长度上限，超出部分截断并写入截断标记，便于判断记录是否完整；错误信息中可能夹带用户输入，写入前做一次敏感词与格式过滤。规则一旦确定，所有采集点按同一口径执行，否则后续检索和聚合会失真。
记录怎么产生：采集、存储与保留期限
采集点通常有两种选择。网关统一采集覆盖面广，所有经过网关的调用都能落下，字段一致性好，适合作为基础记录；应用内埋点能补充业务上下文，例如操作人、关联业务对象，适合对审计和追责要求高的接口。两者可以组合使用，前提是统一字段命名、时间格式和追踪ID的生成规则，否则同一笔调用在两侧对不上。
采集落地时按以下步骤推进：
- 确定采集范围，列出需要记录的接口清单，标注每个接口的敏感等级和用途。
- 定义日志结构，按上一节字段表确定字段名、类型、必填项和脱敏规则，形成字段规范文档。
- 在网关或应用侧实现采集，输出结构化日志，避免自由文本拼接。
- 增加字段校验，对必填字段缺失、格式不符的记录打标或告警，防止脏数据进入存储。
- 建立检索索引，至少对request_id、trace_id、app_id、called_at、status_code建索引，保证按时间和身份能快速定位。
存储与保留按热、温、冷分层设计。热数据保留最近一段时间，支撑日常排障，要求查询响应快；温数据保留稍长周期，支撑周期性审计与计量统计；冷数据归档保存，满足合规要求，查询频率低但需要时可取回。保留期限结合合规要求、业务需要和存储成本确定，并在规范中写明到期后的归档与清理规则，清理动作本身也要留痕，避免误删无法追溯。
访问权限同样需要设计。调用记录包含调用方身份和业务信息，应按角色授权：接口负责人可查自己负责接口的记录，平台运维可查全量但导出需审批，安全与审计角色可只读查询。导出行为应记录操作人、导出范围和导出时间，形成独立的操作日志。
在字段规范和采集任务的评审、跟踪环节，可以把规范文档、采集配置变更和验收任务放在ONES中管理。ONES提供丰富多样的API接口，可快速集成企业系统实现数据打通，这类采集与对接任务的工作项、评审记录和交付物可以在同一处关联，方便接口负责人和平台运维按同一份规范推进。
角色分工与交付物
调用记录方案涉及定义、实现、审查和使用四类工作，责任需要落到具体角色，避免字段规范写完无人执行、采集上线无人验收。
| 角色 | 主要职责 | 交付物 |
|---|---|---|
| 接口负责人 | 确定所负责接口的记录范围、关键参数摘要口径、业务对象关联方式 | 接口级字段说明、接口清单 |
| 平台运维 | 实现网关采集、日志结构统一、存储与索引配置、保留与清理策略 | 采集配置、存储与保留策略、查询视图 |
| 安全与审计 | 审查脱敏规则、访问权限、导出审批流程，确认保留期限满足合规要求 | 审查意见、权限矩阵 |
| 应用开发方 | 在应用内埋点补充业务上下文，按规范输出结构化日志 | 埋点实现、字段自检结果 |
三类交付物构成方案的核心：字段规范回答“记什么”，采集配置回答“怎么记”，查询视图回答“怎么用”。字段规范由接口负责人牵头、安全与审计参与评审后定稿；采集配置由平台运维实现并版本化管理；查询视图按排障、审计、计量三类场景分别提供，让使用方不必自己拼查询条件。
示例：一次失败调用的完整记录
以下为演示情景，用于说明字段如何填写与关联，不代表任何具体产品的实际日志格式。
| 字段 | 取值 | 说明 |
|---|---|---|
| request_id | req-20240612-8f3a2c | 本次调用的唯一标识，排障时首先用它定位 |
| called_at | 2024-06-12T10:23:41.512+08:00 | 毫秒精度，统一东八区 |
| duration_ms | 23 | 快速失败，说明在参数校验阶段即被拒绝 |
| app_id | crm-sync | 调用方应用 |
| credential_id | ak-9d2e**** | 凭证只留标识，密钥不落库 |
| operator | zhangsan | 触发同步的用户 |
| http_method / path | POST /open/v2/issues | 含版本段，便于区分不同版本行为 |
| param_digest | project=42;type=bug;title=登录异常 | 只记关键参数，敏感值已掩码 |
| status_code | 400 | HTTP 层结果 |
| biz_code | INVALID_PARAM | 业务错误码，比状态码更具体 |
| error_message | 字段 type 取值非法，允许值：bug、task | 截断至约定长度，直接指向问题字段 |
| source_ip | 10.12.3.45 | 内网来源，便于判断调用路径 |
| trace_id | trace-7c1b90 | 用它在网关日志与应用日志中检索同一笔调用 |
| business_ref | issue#10231 | 关联的业务对象，追责与复盘时使用 |
这条记录能直接回答排障问题：调用在参数校验阶段失败，错误指向type字段取值。用trace_id在网关侧查到请求进入时间，在应用侧查到参数组装逻辑，两侧时间差可以判断耗时主要发生在哪一段。审计视角看，app_id、credential_id、operator、source_ip齐全，能确认调用来源；计量视角看，status_code与duration_ms可用于统计失败率和响应分布。
上线前的完成检查
方案落地后，用以下清单逐项核对，确认记录真实可用，而非配置存在但数据不可查。
- 字段完整性抽查：抽取近期成功与失败调用各若干条，核对必填字段是否齐全、格式是否符合规范、时间精度是否一致。
- 脱敏与权限验证：检查凭证、Token、密码类参数是否以掩码或哈希形式出现；用不同角色账号分别查询，确认权限边界符合权限矩阵；验证导出是否触发审批与操作留痕。
- 检索与关联可用性验证：用request_id、trace_id、app_id、时间范围分别检索，确认能定位到目标记录；用trace_id串联网关与应用两侧日志，确认能还原完整链路。
- 保留与清理策略生效验证：确认热、温、冷分层配置已生效，到期归档与清理任务按计划执行，清理前有备份或归档记录。
- 异常场景验证：模拟字段缺失、超长参数、错误信息含敏感内容等情况，确认校验、截断与过滤规则按预期工作。
检查中发现的问题应回到字段规范或采集配置中修正，并重新抽查，直到清单各项通过。此后每次接口版本升级或新增接口，都按同一份规范补充记录范围，保持口径一致。
常见问题
接口调用量大时，全量记录会不会带来过高的存储成本？
可以通过分层控制成本。必备字段保持全量记录，保证排障和审计的底线；关键参数摘要、响应大小、关联业务对象这类按需字段，只对敏感等级高或业务重要的接口开启。存储上按热、温、冷分层，热数据保留最近一段时间支撑日常排障，冷数据归档满足合规要求，查询频率低但需要时可取回。保留期限结合合规要求、业务需要和存储成本确定，并在规范中写明到期归档与清理规则。
网关已经统一采集了，应用侧还需要再埋点吗？
取决于记录要支撑的用途。网关采集覆盖面广、字段一致性好，能回答调用方是谁、调用了哪个接口、结果如何。如果审计和追责需要知道操作人、关联的业务对象，这些信息通常只有应用侧掌握，就需要在应用内埋点补充。两者组合使用时，前提是统一字段命名、时间格式和追踪ID的生成规则，否则同一笔调用在两侧对不上，排障时反而增加工作量。
调用记录里出现用户输入内容，应该怎么处理？
按字段规范统一处理，不依赖采集点各自判断。请求头中的凭证、Token、密码类参数一律不落原文，只保留凭证标识或哈希值；请求体与响应体按需记录时设置长度上限，超出部分截断并写入截断标记；错误信息可能夹带用户输入，写入前做一次敏感词与格式过滤。规则确定后所有采集点按同一口径执行，并在上线检查时抽取记录核对脱敏效果。
接口升级或新增接口后，调用记录需要跟着改吗？
需要。接口版本变化可能带来参数结构、错误码和业务对象的调整，记录范围应按同一份字段规范同步补充。建议把接口清单与字段说明作为规范的一部分维护，每次版本升级或新增接口时更新对应条目，并在上线检查中重新抽查字段完整性与检索可用性，保持不同接口之间的口径一致。
调用记录的查询权限应该怎么划分？
按角色授权，避免一份记录对所有人生效。接口负责人可查询自己负责接口的记录；平台运维可查全量，导出需走审批；安全与审计角色以只读方式查询，用于合规检查。导出行为本身应记录操作人、导出范围和导出时间，形成独立的操作日志。权限矩阵建议由安全与审计角色审查确认，并在上线检查时用不同角色账号实际验证边界。
