启用分布式跟踪

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面演示了为 Apigee 运行时配置分布式跟踪所需的步骤。如果您刚开始使用分布式跟踪系统，并且希望了解详情，请参阅了解分布式跟踪。

简介

通过分布式跟踪系统，您可以在分布在多个应用、服务和数据库以及中介（如代理）的软件系统中跟踪请求。这些跟踪系统会生成报告，其中显示请求在每个步骤中花费的时间。通过跟踪报告，您还可以深入了解请求期间调用的各种服务，从而更深入地了解软件系统中每个步骤发生的情况。

Apigee Edge 中的跟踪记录工具和 Apigee 中的调试工具可用于排查和监控 API 代理。但是，这些工具不会向分布式跟踪服务器（如 Cloud Trace 或 Jaeger）发送任何数据。如需在分布式跟踪报告中查看 Apigee 运行时数据，您必须在 Apigee 运行时中明确启用分布式跟踪。启用跟踪功能后，运行时可以将跟踪记录数据发送到分布式跟踪服务器并参与现有跟踪记录。因此，您可以在一个位置查看 Apigee 生态系统内外的数据。

您可以在分布式跟踪报告中查看以下信息：

整个流的执行时间。
收到请求的时间。
请求发送到目标的时间。
从目标接收响应的时间。
流中每项政策的执行时间。
服务标注和目标流的执行时间。
响应发送到客户端的时间。

在分布式跟踪报告中，您可以以 span 形式查看流的执行详情。span 是指跟踪记录中流所花费的时间。执行流所需的时间会以执行流中的每个政策所需的汇总时间形式显示。您可以以单个 span 的形式查看以下流：

请求
- 代理
  - Preflow
  - PostFlow
- 目标
  - Preflow
  - PostFlow
响应
- 代理
  - Preflow
  - PostFlow
- 目标
  - Preflow
  - PostFlow

启用分布式跟踪后，Apigee 运行时将默认跟踪一组预定义变量。如需了解详情，请参阅跟踪报告中的默认跟踪变量。您可以使用 TraceCapture 政策扩展默认运行时行为并跟踪其他流、政策或自定义变量。如需了解详情，请参阅 TraceCapture 政策。

对 Apigee 的传入 API 调用可能包含跟踪记录标头，因为该调用是现有跟踪记录的一部分。在这种情况下，Apigee 会参与现有跟踪并将标头传播到传出 API 调用。Apigee 运行时可以理解 Zipkin B3 标头格式。因此，在参与现有跟踪时，它会识别 x-b3-traceid、x-b3-spanid 和 x-b3-sampled 标头。但是，如果传入 API 调用中没有跟踪记录标头，Apigee 会添加其跟踪记录标头并将其传播到传出 API 调用。其他服务可以访问标头并在必要时参与跟踪。

跟踪报告中的默认跟踪记录变量

启用分布式跟踪后，您可以在跟踪报告中查看以下预定义变量集。变量在以下 span 中可见：

POST_RESP_SENT:：从目标服务器收到响应后，系统会添加此 span。
POST_CLIENT_RESP_SENT:：在将代理响应发送到客户端后，系统会添加此 span。

POST_RESP_SENT span 中的变量

以下变量在 POST_RESP_SENT span 中可见：

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
RESPONSE_STATUS_CODE (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

POST_CLIENT_RESP_SENT span 中的变量

以下变量在 POST_CLIENT_RESP_SENT span 中可见：

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME (environment.name)
FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

受支持的分布式跟踪系统

Apigee 运行时支持以下分布式跟踪系统：

Cloud Trace
Jaeger

您可以配置 Apigee 运行时，以将跟踪记录数据发送到 Cloud Trace 或 Jaeger 系统。

由于在 Apigee 运行时中跟踪所有 API 调用会影响性能，因此 Apigee 允许您配置概率采样率。通过使用该采样率，您可以指定为分布式跟踪发送的 API 调用的数量。例如，如果您将采样率指定为 0.4，那么 40% 的 API 调用会发送以用于跟踪。如需了解详情，请参阅性能考虑因素。

可配置的采样率上限为 0.5。

为 Cloud Trace 配置 Apigee 运行时

Apigee 运行时和 Apigee Hybrid 运行时都支持使用 Cloud Trace 的分布式跟踪。如果您使用的是 Jaeger，则可以跳过本部分并继续执行为 Jaeger 启用分布式跟踪。

为 Cloud Trace 配置 Apigee 运行时

如需在 Apigee 运行时中使用 Cloud Trace，您的 Google Cloud 项目必须启用 Cloud Trace API。此设置可让您的 Google Cloud 项目接收已经过身份验证的来源的跟踪记录数据。

如需确认已启用 Cloud Trace API，请执行以下操作：

在 Google Cloud 控制台中，转到 API 和服务：
转到“API 和服务”
点击启用 API 和服务。
在搜索栏中输入 Trace API。
如果系统显示 API 已启用，则表示此 API 已启用，您无需执行任何操作。否则，请点击启用。

为 Cloud Trace 配置 Apigee Hybrid 运行时

您必须启用 Cloud Trace API 才能将 Cloud Trace 与 Apigee Hybrid 运行时搭配使用。如需确认已启用 Cloud Trace API，请按照为 Cloud Trace 配置 Apigee 运行时中的步骤操作。

除了启用 Cloud Trace API 之外，您还必须添加 iam.gserviceaccount.com 服务账号，以将 Cloud Trace 与 Hybrid 运行时搭配使用。如需添加服务账号以及所需的角色和密钥，请执行以下步骤：

创建新服务账号：

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

向服务账号添加 IAM 政策绑定：

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

创建服务账号密钥：
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
如果服务账号密钥未得到适当的管理，则会带来安全风险。您需负责私钥的安全性以及执行管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。
将服务账号添加到 overrides.yaml 文件。

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

将更改应用于运行时

apigeectl apply -f overrides.yaml --env=ENV_NAME

启用分布式跟踪

在为 Cloud Trace 或 Jaeger 启用分布式跟踪之前，请创建以下环境变量：

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

其中：

TOKEN 使用不记名令牌定义身份验证标头。调用 Apigee API 时需使用此标头。如需了解详情，请参阅 print-access-token 命令的参考页面。
ENV_NAME 是您的组织中环境的名称。
PROJECT_ID 是您的 Google Cloud 项目的 ID。

为 Cloud Trace 启用分布式跟踪

以下示例展示了如何为 Cloud Trace 启用分布式跟踪：

执行此 Apigee API 调用：
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
    "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
```
示例请求正文包含以下元素：
- samplingRate 已设置为 0.1。这表示大约 10% 的 API 调用会发送到分布式跟踪。如需详细了解如何为运行时环境设置 samplingRate，请参阅性能注意事项。
- exporter 参数设置为 CLOUD_TRACE。
- 端点设置为您要发送跟踪记录的 Google Cloud 项目。注意：这必须与在配置步骤中完成的服务账号匹配。
成功的响应类似于以下内容：
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

为 Jaeger 启用分布式跟踪

以下示例展示了如何为 Jaeger 启用分布式跟踪：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

在此示例中：

samplingRate 设置为 0.4，这表示大约 40% 的 API 调用会发送到分布式跟踪。
exporter 参数设置为 JAEGER。
端点设置为 Jaeger 的安装和配置位置。

运行该命令时，您会看到类似于以下内容的响应：

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

查看分布式跟踪配置

如需在运行时中查看现有分布式跟踪配置，请登录运行时，然后运行以下命令：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

运行该命令时，您会看到类似于以下内容的响应：

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

更新分布式跟踪配置

以下命令展示了如何更新 Cloud Trace 的现有分布式跟踪配置：

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

运行该命令时，您会看到类似于以下内容的响应：

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

在此示例中，采样率更新为 0.05。

如需更新 Jaeger 的配置，请将请求中的 exporter 字段设置为 JAEGER。

停用分布式跟踪配置

以下示例展示了如何停用为 Cloud Trace 配置的分布式跟踪：

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

运行该命令时，您会看到类似于以下内容的响应：

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

替换 API 代理的跟踪记录设置

当您在 Apigee 运行时中启用分布式跟踪后，运行时中的所有 API 代理都会使用相同的配置进行跟踪。但是，您可以替换 API 代理或一组 API 代理的分布式跟踪配置。这可让您更精细地控制跟踪配置。

以下示例替换了 hello-world API 代理的分布式跟踪配置：

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

您可以替换配置，以排查 API 代理特有的问题，而无需更改所有 API 代理的配置。

更新跟踪记录设置替换

如需更新 API 代理或 API 代理组的跟踪配置替换，请按以下步骤操作：

使用以下命令检索跟踪配置的任何现有替换：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

此命令应返回类似于如下所示的响应，其中包含一个“name”字段，该字段用于标识受替换约束的代理：

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

如需更新代理，请使用“name”字段的值以及更新后的字段值向该代理的替换配置发送 POST 请求。例如：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

删除跟踪记录设置替换

如需删除 API 代理或 API 代理组的跟踪配置替换，请按以下步骤操作：

使用以下命令检索跟踪配置的任何现有替换：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

此命令应返回类似于如下所示的响应，其中包含一个“name”字段，该字段用于标识受替换约束的代理：

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

如需删除代理，请使用“name”字段的值以及更新后的字段值向该代理的替换配置发送 DELETE 请求。例如：

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \

性能考虑因素

当您为 Apigee 运行时环境启用分布式跟踪时，预计会影响性能。影响可能会导致内存使用量增加，CPU 要求增加，延迟时间增加。影响的程度在一定程度上取决于 API 代理的复杂程度（例如政策数量）和概率采样率（设置为 samplingRate）。采样率越高，对性能的影响就越大。虽然性能影响取决于许多因素，但是在使用分布式跟踪时，性能可能会下降 10-20%。

对于流量要求高、延迟时间要求低的环境，建议的概率采样率小于或等于 10%。如果要使用分布式跟踪进行问题排查，请考虑仅针对特定 API 代理增加概率采样 (samplingRate)。