跟踪您的 API

OpenAPI   |  gRPC

部署 Extensible Service Proxy (ESP) 或 Extensible Service Proxy V2 (ESPv2) 和 API 的后端代码后，代理会拦截所有请求并执行所有必要的检查，然后再将请求转发到 API 后端。当后端响应时，代理会收集并报告遥测数据。代理捕获的遥测数据之一是使用 Cloud Trace 跟踪的数据。

本页面介绍了如何：

• 在 Google Cloud Console 中查看跟踪记录。
• 估算跟踪记录的费用。
• 配置代理以停用跟踪记录采样。

查看跟踪记录

跟踪记录可跟踪发送到 API 的传入请求、各种事件（例如 RPC 调用或插桩的代码部分）以及每个事件的确切时间。这些事件在跟踪记录中表示为 span。

如需查看项目的跟踪记录，请转到 Google Cloud Console 中的 Cloud Trace 页面：

转到 Trace

在跟踪列表页面上，您可以展开每个跟踪记录的细目，并查看 ESP 在跟踪记录中创建的 span。您可以使用过滤器查看单个 API 或操作的跟踪记录。

为您的 API 创建的跟踪记录和 span 会有所不同，具体取决于您的 API 是使用 ESPv2 还是 ESP。下面汇总了每种实现的跟踪记录格式。

如需详细了解跟踪记录列表页面，请参阅在 Cloud Console 中查看跟踪记录。

ESPv2 创建的 Span

ESPv2 使用以下格式创建跟踪记录：

ESPv2 会为每个跟踪记录创建 2 个 span：

• 用于整个请求和响应的 ingress OPERATION_NAME span。
• 时间 ESPv2 的 router BACKEND egress span 会等待后端处理请求并做出响应。这包括 ESPv2 和后端之间的网络跃点。

根据 API 的配置，ESPv2 可能会创建其他 span：

• 如果您的 API 需要身份验证，ESPv2 会将需要验证其身份的公钥缓存 5 分钟。如果缓存中没有公钥，则 ESPv2 将检索并缓存公钥，然后创建 JWT Remote PubKey Fetch span。
• 如果您的 API 需要 API 密钥，则 ESPv2 缓存验证 API 密钥所需的信息。如果缓存中没有该信息，ESPv2 将调用 Service Control 并创建 Service Control remote call: Check span。

通常，ESPv2 仅会为阻止传入请求的网络调用创建 span。系统不会跟踪非阻塞请求。任何本地处理都将创建时间事件，而不是 span。例如：

• 配额强制执行需要远程调用，但调用并不发生在 API 请求的路径中，并且跟踪记录中不存在与其关联的 span。
• ESPv2 会缓存 API 密钥一小段时间。任何使用缓存的请求都会有与跟踪记录相关联的时间事件。

ESP 创建的 span

警告：ESP 未提供 span 的相关详情。此外，它还会创建没有意义的 span。请迁移到 ESPv2 以查看遵循跟踪最佳做法的详细跟踪记录。

ESP 使用以下格式创建跟踪记录：

ESP 至少会为每个跟踪记录创建 4 个 span：

• 用于整个请求和响应的 span。
• CheckServiceControl span，用于调用 Service Control 的 services.check 方法以获取 API 的配置。
• QuotaControl span，用于检查您的 API 上是否配置了配额。
• Backend span，用于跟踪 API 后端代码中花费的时间。

根据 API 的配置，ESP 会创建额外的 span：

• 如果您的 API 需要身份验证，ESP 会在每条跟踪记录中创建一个 CheckAuth span。为了对请求进行身份验证，ESP 会将身份验证所需的公钥缓存 5 分钟。如果缓存中没有公钥，则 ESP 将检索并缓存公钥，然后创建 HttpFetch span。
• 如果您的 API 需要 API 密钥，ESP 会在每条跟踪记录中创建一个 CheckServiceControlCache span。ESP 会缓存验证 API 密钥所需的信息。如果缓存中没有该信息，ESP 将调用 Service Control 并创建 Call ServiceControl server span。
• 如果您为 API 设置了配额，ESP 会在每条跟踪记录中创建 QuotaServiceControlCache span。ESP 会缓存检查配额所需的信息。如果缓存中没有该信息，ESP 将调用 Service Control 并创建 Call ServiceControl server span。

跟踪记录采样率

ESP 会对发送到 API 的少量请求进行采样，以获取跟踪数据。为了控制采样率，ESP 会维护请求计数器和计时器。采样率取决于每秒钟向 API 发送的请求数。如果一秒内没有请求，则 ESP 不会发送跟踪记录。

如果一秒内的请求数：

• 小于或等于 999，ESP 将发送 1 个跟踪记录。
• 在 1000 到 1999 之间，ESP 将发送 2 个跟踪记录。
• 在 2000 到 2999 之间，ESP 将发送 3 个跟踪记录。
• 等等。

总之，您可以使用 ceiling 函数估算采样率： ceiling(requests per second/1000)

估算跟踪记录的成本

要估算跟踪记录的成本，您需要估算 ESP 在一个月内发送到 Trace 的 span 数。

要估算每月的 span 数，请执行以下操作：

1. 估算您的 API 每秒收到的请求数。如需获取这项估算值，您可以使用 Endpoints > 服务页面上的请求图表或 Cloud Logging。如需了解详情，请参阅监控您的 API。
2. 计算 ESP 每秒向 Trace 发送的跟踪记录数：ceiling(requests per second/1000)
3. 估算每个跟踪记录中的 span 数。要获取此估算值，您可以使用 ESP 创建的 span 中的信息，或查看跟踪记录列表页面，以获取您的 API 跟踪记录。
4. 估算 API 在一个月内获取流量的秒数。例如，有些 API 仅在一天中的某些时间段内获取请求，而其他一些 API 则是偶尔获取请求。
5. 将一个月内的秒数乘以 span 数。

例如：

1. 假设 API 每秒的最大请求数为 5。
2. 跟踪记录采样率为：ceiling(5/1000) = 1
3. API 未配置配额，不需要 API 密钥也不需要进行身份验证。因此，ESP 为每个跟踪记录创建的 span 数为 4。
4. 此 API 仅在周一至周五的工作时间获取请求。API 在一个月内获取流量的秒数大约为：3600 X 8 X 20 = 576000
5. 每月的 span 数约为：576000 x 4 = 2304000

在您知道一个月内的大致 span 数后，请参阅 Stackdriver 价格页面详细了解价格信息。

停用跟踪记录采样

如果要阻止 ESP 对请求进行采样并发送跟踪记录，则可以设置 ESP 启动选项并重启 ESP。ESP 向 Cloud Trace 发送的跟踪记录与 Endpoints > 服务页面上显示的图表无关。在您停用跟踪记录采样后，图表仍继续可用。

以下部分假设您已经部署 API 和 ESP，或者您熟悉部署流程。如需了解详情，请参阅部署 API 后端。

App Engine

要在 App Engine 柔性环境中停用 ESP 跟踪记录采样，请执行下列操作：

1. 修改 app.yaml 文件。在 endpoints_api_service 部分中，添加 trace_sampling 选项，并将其值设置为 false。例如：

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false
   

   如果您的应用基于微服务，您必须在每个 app.yaml 文件中添加 trace_sampling: false。

2. 如果您最近尚未更新 Cloud SDK，请运行以下命令：

   gcloud components update
   

3. 保存 app.yaml 文件。
4. 将后端代码和 ESP 部署到 App Engine：

   gcloud app deploy
   

要重新启用跟踪记录采样，请执行以下操作：

1. 从 app.yaml 中移除 trace_sampling 选项。
2. 将后端代码和 ESP 部署到 App Engine：

   gcloud app deploy
   

Compute Engine

要在装有 Docker 的 Compute Engine 上停用 ESP 跟踪记录采样，请执行以下操作：

1. 连接到您的虚拟机实例：

   gcloud compute ssh [INSTANCE_NAME]

2. 在 docker run 命令的 ESP 标志中，添加 --disable_cloud_trace_auto_sampling 选项：

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. 发出 docker run 命令以重启 ESP。

要重新启用跟踪记录采样，请执行以下操作：

1. 移除 --disable_cloud_trace_auto_sampling。
2. 发出 docker run 命令以重启 ESP。

GKE

要在 GKE 上停用 ESP 跟踪记录采样，请执行以下操作：

1. 打开您的部署清单文件（即 deployment.yaml），并将以下内容添加到 containers 部分：

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. 使用 kubectl create 命令启动 Kubernetes 服务：

   kubectl create -f deployment.yaml

要重新启用跟踪记录采样，请执行以下操作：

1. 移除 --disable_cloud_trace_auto_sampling 选项。
2. 启动 Kubernetes 服务：

   kubectl create -f deployment.yaml

如果您是在没有 Docker 容器的 Compute Engine 虚拟机实例上运行 ESP，则 --disable_cloud_trace_auto_sampling 选项没有等效的虚拟机实例元数据键值对。若要停用跟踪记录采样功能，您必须在容器中运行 ESP。

客户端可以通过向请求添加 X-Cloud-Trace-Context 标头来强制跟踪请求，如强制跟踪请求中所述。如果请求中包含 X-Cloud-Trace-Context 标头，即使您已停用跟踪记录采样功能，ESP 也会向 Trace 发送跟踪记录数据。

跟踪上下文传播

对于分布式跟踪，请求标头可以包含用于指定跟踪记录 ID 的跟踪上下文。当 ESPv2 创建新的跟踪记录 span 并将它们发送到 Cloud Trace 时，将使用跟踪记录 ID。跟踪记录 ID 用于搜索所有跟踪记录以及为单个请求联接 span。如果请求中未指定跟踪上下文，而且跟踪功能已启用，则会为所有跟踪记录 span 生成随机跟踪记录 ID。

在以下示例中，Cloud Trace 将 ESPv2 (1) 创建的 span 与单个请求的后端 (2) 进行关联。这有助于调试整个系统的延迟问题：

如需了解详情，请参阅 OpenTelemetry Core 概念：上下文传播

注意：分布式跟踪要求您的客户端和/或后端支持跟踪。这超出了本文档的范围。我们建议使用 OpenTelemetry。

支持的标头

ESPv2 支持以下跟踪上下文传播标头：

• traceparent：标准 W3C 跟踪上下文传播标头。受大多数现代跟踪框架支持。
• x-cloud-trace-context：GCP 的跟踪记录上下文传播标头。受旧版跟踪框架和 Google 的库支持，但针对特定供应商。
• grpc-trace-bin：gRPC 后端将跟踪记录上下文传播标头与 OpenCensus 跟踪库配合使用。

如果要构建新应用，建议使用 traceparent 跟踪记录上下文传播。默认情况下，ESPv2 将提取和传播此标头。如需详细了解如何更改默认行为，请参阅 ESPv2 跟踪启动选项。

注意：与 ESPv2 不同，ESP 中的跟踪记录上下文传播需要通过启动选项手动启用。ESP 不支持 traceparent 标头。