跟踪您的 API

部署 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 的 span 的跟踪记录示例

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 span 的跟踪记录示例

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

  • 用于整个请求和响应的 span。
  • CheckServiceControl span,用于调用 Service Controlservices.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) 进行关联。这有助于调试整个系统的延迟问题:

ESPv2 的跟踪记录上下文传播示例

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

支持的标头

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

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

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