想要在所有代理中使用关联 ID 进行日志记录——在 Apigee X 中的实现方法

Source: Dev.to

（请提供需要翻译的正文内容，我才能为您完成简体中文翻译。）

介绍：“调试为何如此痛苦？” 🤯

想象这种情形。

客户报告：

“我的请求在某处失败了……但我们不知道具体位置。”

你检查：

• 客户端日志 ❌
• Apigee 日志 ❌
• 后端日志 ❌

没有任何线索匹配。每个系统都有日志——但 没有共同的线索 将它们联系起来。

这是一项在 API 管理 中最常见的痛点之一，尤其是在以下情况下：

• 多个 API 代理
• 微服务
• 异步调用
• 高流量

解决方案？

👉 关联 ID（Correlation IDs）

而在 Apigee X 中强制执行它们 在所有 API 中保持一致 是最佳选择。

在本博客中，你将了解：

• 什么是关联 ID（通俗解释）
• 为什么它们重要
• 如何 一次 实现并在所有地方复用
• 针对 Apigee X 的生产级最佳实践

核心概念：简明解释关联 ID（ELI5） 🧒

快递追踪类比 📦

把 API 请求想象成快递包裹。每个包裹都有 唯一的追踪号，贯穿整个过程：

• 揽件
• 运输
• 投递

👉 关联 ID 就是 API 请求的追踪号。从 Apigee 到后端的每一条日志都包含 相同的 ID。

什么是关联 ID？

• 唯一标识符（通常是 UUID）
• 附加在每个 API 请求上
• 通过 HTTP 头在系统之间传递

示例头部

X-Correlation-Id: 9f2c1a6b-1c42-4f87-a1d2-123456789abc

为什么在 Apigee X 的 API 代理中关联 ID 很重要

对于 Apigee X，关联 ID 对以下方面至关重要：

• Distributed logging
• Faster incident resolution
• Better API traffic management
• Stronger API‑security audits

应该在哪里实现关联 ID？

最佳位置是API proxy layer，而不是后端服务。

为什么？

• 集中化
• 一致性
• 无需更改后端代码
• 适用于 all APIs

这就是 API Proxies in Apigee X 非常适合的原因。

Source:

步骤详解：在 Apigee X 中实现关联 ID

目标

1. 如果客户端提供 X-Correlation-Id，则接受它。
2. 如果缺失，则生成一个。
3. 将其传递给后端、响应以及日志。

步骤 1️⃣：生成关联 ID（JavaScript 策略）

策略名称： JS-Generate-Correlation-Id

// Check if correlation ID already exists
var correlationId = context.getVariable("request.header.X-Correlation-Id");

if (!correlationId) {
    // Generate a simple UUID‑like value
    correlationId = java.util.UUID.randomUUID().toString();
}

// Store it in a flow variable
context.setVariable("correlation.id", correlationId);

• 将此策略附加到 PreFlow → Request。
• 确保它在 每个请求 中运行。

步骤 2️⃣：将关联 ID 添加到请求头（AssignMessage）

<AssignMessage name="AM-Add-Correlation-Id-Request">
    <Set>
        <Headers>
            <Header name="X-Correlation-Id">{correlation.id}</Header>
        </Headers>
    </Set>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

• 在请求流中，在 JavaScript 策略之后 附加。

步骤 3️⃣：将关联 ID 添加到响应头（AssignMessage）

<AssignMessage name="AM-Add-Correlation-Id-Response">
    <Set>
        <Headers>
            <Header name="X-Correlation-Id">{correlation.id}</Header>
        </Headers>
    </Set>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

• 在响应 PreFlow 中 附加。

步骤 4️⃣：记录关联 ID（MessageLogging）

<MessageLogging name="ML-Log-Correlation-Id">
    <Message>
        CorrelationId={correlation.id},
        Proxy={apiproxy.name},
        RequestPath={request.path}
    </Message>
    <LogLevel>info</LogLevel>
</MessageLogging>

• 现在每条日志行都带有可追踪的 ID。

端到端流程可视化

Client
  ↓ (X-Correlation-Id)
Apigee X Proxy
  ↓ (same ID)
Backend Service
  ↓
Response (same ID)

Best Practices for Correlation IDs in Apigee X ✅

1. Always generate at the edge – never rely on backends.
   始终在边缘生成 – 切勿依赖后端。

2. Use a single header name – X-Correlation-Id. Consistency matters.
   使用单一的 Header 名称 – X-Correlation-Id。一致性很重要。

3. Log it everywhere – Apigee logs, backend logs, error responses.
   在所有地方记录 – 包括 Apigee 日志、后端日志、错误响应。

4. Don’t reuse request IDs – Correlation ID ≠ Apigee message ID.
   不要复用请求 ID – Correlation ID ≠ Apigee 消息 ID。

5. Use Shared Flows for scale – create one shared flow and attach it to all proxies.
   使用 Shared Flows 实现规模化 – 创建一个共享流并将其附加到所有代理。

常见错误避免 ❌

• 每个请求生成多个 ID
• 覆盖客户端提供的 ID
• 忘记在响应中返回 ID
• 为每个代理单独实现逻辑（复制‑粘贴地狱）

为什么这对 API 管理是个游戏规则改变者

使用关联 ID：

• 调试时间大幅下降
• 生产事故更易追踪
• API 可观测性提升
• 团队在故障期间使用统一语言

这对于大型系统中的严肃 API 管理 来说是 基本要求。

结论：小改动，巨大影响 🎯

在 Apigee X 的 API 代理 中添加关联 ID 是：

• 易于实现
• 与后端无关
• 功能极其强大

正确实现后，每个 API 请求都会携带可追踪的标识符，统一整个请求‑响应链路的日志，将混乱的调试过程转变为流畅、可观测的系统。

行动号召 💬

你今天是如何追踪请求的？

👇 在下方评论：

• 你已经在使用关联 ID 吗？
• 想要一个 Shared Flow 模板 吗？
• 需要 支付级别的日志示例 吗？

📌 关注获取更多关于 Apigee X、API 安全 和 API 流量管理 的洞见。