跟踪您的 API

部署 Extensible Service Proxy (ESP) 和 API 的后端代码后,ESP 会拦截所有请求并执行所有必要的检查,然后再将请求转发到 API 后端。当后端响应时,ESP 会收集并报告遥测数据。在 ESP 捕获的遥测数据中,有一部分数据来自 Cloud Trace 的跟踪记录。

本页面介绍了如何:

  • 在 Google Cloud Console 中查看跟踪记录。
  • 估算您的 Trace 费用。
  • 将 ESP 配置为停用跟踪记录采样。

查看 API 的跟踪记录

要查看 API 的跟踪记录,请执行以下操作:

  1. 转到项目的 Endpoints > 服务页面:

    转到“Endpoints 服务”页面

  2. 如果您有多个 API,请点击要查看其跟踪记录的 API。

  3. 确保您已进入概览标签。

  4. 向下滚动,然后点击查看跟踪数据。随即将显示 Cloud Trace 跟踪记录列表页面。

跟踪记录可跟踪发送到 API 的传入请求、各种事件(例如已发生的 RPC 调用或已装配的代码段)以及精确计时。这些事件在跟踪记录中表示为 span

跟踪列表页面上,您可以展开每个跟踪记录的细目,并查看 ESP 在跟踪记录中创建的 span。

包含 span 的跟踪记录示例

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

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 标头以强制跟踪请求(详情请参阅 Trace 问题排查)。如果请求中包含 X-Cloud-Trace-Context 标头,即使您已停用跟踪记录采样功能,ESP 也会向 Trace 发送跟踪记录数据。