部署 Extensible Service Proxy (ESP) 或 Extensible Service Proxy V2 (ESPv2) 和 API 的后端代码后,代理会拦截所有请求并执行所有必要的检查,然后再将请求转发到 API 后端。当后端响应时,代理会收集并报告遥测数据。代理捕获的遥测数据之一是使用 Cloud Trace 跟踪的数据。
本页面介绍了如何:
- 在 Google Cloud Console 中查看跟踪记录。
- 估算跟踪记录的费用。
- 配置代理以停用跟踪记录采样。
查看跟踪记录
跟踪记录可跟踪发送到 API 的传入请求、各种事件(例如 RPC 调用或插桩的代码部分)以及每个事件的确切时间。这些事件在跟踪记录中表示为 span。
如需查看项目的跟踪记录,请转到 Google Cloud Console 中的 Cloud 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 使用以下格式创建跟踪记录:
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 数,请执行以下操作:
- 估算您的 API 每秒收到的请求数。如需获取这项估算值,您可以使用 Endpoints > 服务页面上的请求图表或 Cloud Logging。如需了解详情,请参阅监控您的 API。
- 计算 ESP 每秒向 Trace 发送的跟踪记录数:
ceiling(requests per second/1000)
- 估算每个跟踪记录中的 span 数。要获取此估算值,您可以使用 ESP 创建的 span 中的信息,或查看跟踪记录列表页面,以获取您的 API 跟踪记录。
- 估算 API 在一个月内获取流量的秒数。例如,有些 API 仅在一天中的某些时间段内获取请求,而其他一些 API 则是偶尔获取请求。
- 将一个月内的秒数乘以 span 数。
例如:
- 假设 API 每秒的最大请求数为 5。
- 跟踪记录采样率为:ceiling(5/1000) = 1
- API 未配置配额,不需要 API 密钥也不需要进行身份验证。因此,ESP 为每个跟踪记录创建的 span 数为 4。
- 此 API 仅在周一至周五的工作时间获取请求。API 在一个月内获取流量的秒数大约为:3600 X 8 X 20 = 576000
- 每月的 span 数约为:576000 x 4 = 2304000
在您知道一个月内的大致 span 数后,请参阅 Stackdriver 价格页面详细了解价格信息。
停用跟踪记录采样
如果要阻止 ESP 对请求进行采样并发送跟踪记录,则可以设置 ESP 启动选项并重启 ESP。ESP 向 Cloud Trace 发送的跟踪记录与 Endpoints > 服务页面上显示的图表无关。在您停用跟踪记录采样后,图表仍继续可用。
以下部分假设您已经部署 API 和 ESP,或者您熟悉部署流程。如需了解详情,请参阅部署 API 后端。
App Engine
要在 App Engine 柔性环境中停用 ESP 跟踪记录采样,请执行下列操作:
- 修改
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
。 - 如果您最近尚未更新 Cloud SDK,请运行以下命令:
gcloud components update
- 保存
app.yaml
文件。 - 将后端代码和 ESP 部署到 App Engine:
gcloud app deploy
要重新启用跟踪记录采样,请执行以下操作:
- 从
app.yaml
中移除trace_sampling
选项。 - 将后端代码和 ESP 部署到 App Engine:
gcloud app deploy
Compute Engine
要在装有 Docker 的 Compute Engine 上停用 ESP 跟踪记录采样,请执行以下操作:
- 连接到您的虚拟机实例:
gcloud compute ssh [INSTANCE_NAME]
- 在
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
- 发出
docker run
命令以重启 ESP。
要重新启用跟踪记录采样,请执行以下操作:
-
移除
--disable_cloud_trace_auto_sampling
。 - 发出
docker run
命令以重启 ESP。
GKE
要在 GKE 上停用 ESP 跟踪记录采样,请执行以下操作:
- 打开您的部署清单文件(即
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" ]
- 使用
kubectl create
命令启动 Kubernetes 服务:kubectl create -f deployment.yaml
要重新启用跟踪记录采样,请执行以下操作:
- 移除
--disable_cloud_trace_auto_sampling
选项。 - 启动 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 概念:上下文传播
支持的标头
ESPv2 支持以下跟踪上下文传播标头:
traceparent
:标准 W3C 跟踪上下文传播标头。受大多数现代跟踪框架支持。x-cloud-trace-context
:GCP 的跟踪记录上下文传播标头。受旧版跟踪框架和 Google 的库支持,但针对特定供应商。grpc-trace-bin
:gRPC 后端将跟踪记录上下文传播标头与 OpenCensus 跟踪库配合使用。
如果要构建新应用,建议使用 traceparent
跟踪记录上下文传播。默认情况下,ESPv2 将提取和传播此标头。如需详细了解如何更改默认行为,请参阅 ESPv2 跟踪启动选项。