API 设计 / 系统课时

设计结构化 GraphQL 日志

设计结构化 GraphQL 日志

本课解决 GraphQL 请求“日志很多却无法定位”的问题:把一次操作压缩成可检索的结构化事件,用请求 ID 串联链路,用操作签名聚合同类请求,同时避免把查询文本和敏感变量直接写入日志。

学习目标

  • 设计稳定、低基数且可检索的 GraphQL 日志字段
  • 用操作签名、耗时和错误类别定位慢请求与失败请求
  • 对变量执行脱敏,并避免记录原始查询和秘密值

把一次 GraphQL 操作记成一个事件

最有价值的日志不是 Resolver 里零散的字符串,而是操作结束时的一条完成事件。它应描述“谁来关联、执行了什么、花了多久、结果怎样”,并保持字段名称稳定,便于日志平台建立索引和聚合。

建议至少记录 requestId、operationName、operationType、operationSignature、durationMs 与 errorCategory。HTTP 状态码可以作为辅助字段,但不能把 200 等同于成功:GraphQL 响应可能在 HTTP 200 下仍包含 errors。

operationName 适合人读,operationSignature 适合机器聚合。签名优先使用 persisted query 的哈希;没有 persisted query 时,应基于解析后的文档做规范化后再哈希,而不是简单删除空格。不要把原始 query 当日志标签或索引字段,否则既可能泄露业务细节,也会制造高基数。

GraphQL 请求从提取上下文到生成结构化日志事件的数据流

用固定字段控制可检索性

字段应优先表达有限枚举或稳定标识。错误类别可以把框架和下游的细碎错误码归并为 validation、authentication、authorization、bad_input、timeout、downstream、resolver、internal 等少量类别,再把原始错误码放到非聚合字段中。

请求 ID 适合日志关联,却不适合作为指标标签;用户 ID、变量值、原始 query 同样不应进入高基数维度。日志可以保留这些事件级字段,但敏感值必须删除或掩码,并遵守日志保留期与访问控制。

实现一个可验证的日志事件

下面脚本可直接用 Node.js 18+ 运行。示例用固定查询计算 SHA-256 签名,并对变量中的 token 做递归脱敏;真实服务中应在 GraphQL 文档解析和执行完成后调用同类逻辑。

js
const { createHash } = require("node:crypto");

function redact(value, sensitiveKeys = new Set(["password", "token", "cookie"])) {
  if (Array.isArray(value)) return value.map((item) => redact(item, sensitiveKeys));
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [
        key,
        sensitiveKeys.has(key.toLowerCase()) ? "<REDACTED>" : redact(item, sensitiveKeys),
      ]),
    );
  }
  return value;
}

const query = "query GetProduct($id: ID!) { product(id: $id) { id name } }";
const operationSignature = createHash("sha256").update(query).digest("hex");

const event = {
  requestId: "req-7f3",
  operationName: "GetProduct",
  operationType: "query",
  operationSignature,
  durationMs: 42,
  errorCategory: null,
  variablesSafe: redact({ id: "p-42", token: "secret-token" }),
};

console.log(JSON.stringify(event));

预期输出:

text
{"requestId":"req-7f3","operationName":"GetProduct","operationType":"query","operationSignature":"33e1cb016aa3fa31c26287e7691c0843ded27c42d8e2650d8b1269088ab57f38","durationMs":42,"errorCategory":null,"variablesSafe":{"id":"p-42","token":"<REDACTED>"}}

实际生产环境中的 requestId、耗时和签名会随请求变化;若签名来自 persisted query,应直接复用客户端与服务端约定的哈希,避免两套算法产生不同分组。

让错误日志能直接回答问题

GraphQL 错误最好在完成事件中记录“类别 + 数量 + 是否影响顶层数据”,而不是只保存异常消息。异常堆栈适合单独的错误事件,并通过同一个 requestId 关联;这样常规查询不会因为大段堆栈而膨胀。

排障时先按 operationSignature 聚合,再比较 durationMs 与 errorCategory。如果某一签名突然变慢,再沿 requestId 进入 Resolver 或下游服务日志。结构化字段的价值正在于:先用低基数维度缩小范围,再用事件级标识追到单次请求。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计结构化 GraphQL 日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通