配置导出

本页面介绍了如何使用 Cloud Trace API 和 Google Cloud CLI 导出跟踪记录。您必须使用 274.0.0 或更高版本的 Google Cloud CLI。如需了解如何更新 Google Cloud CLI,请参阅 gcloud components update

本页面上的一些示例是使用 curl 生成的。如需了解如何配置此工具,请参阅使用 curl

如需查看说明使用 Google Cloud CLI 命令列出、创建、描述、更新和删除接收器的示例,请参阅端到端示例

术语

为了简化本页面上的示例,我们使用了环境变量。

Google Cloud CLI 示例使用以下环境变量:

  • SINK_ID:接收器的名称或标识符。例如 my-sink。您无需向 Google Cloud CLI 提供完全限定的命令,因为它可以确定您的 Google Cloud 项目。
  • DESTINATION:存储目标的完全限定名称。这必须是一个 BigQuery 数据集。例如,有效目标为:

    bigquery.googleapis.com/projects/DESTINATION_PROJECT_NUMBER/datasets/DATASET_ID
    

    其中 DESTINATION_PROJECT_NUMBER 是目标的 Google Cloud 项目编号,DATASET_ID 是 BigQuery 数据集标识符。

curl 示例使用以下环境变量:

  • ACCESS_TOKEN:存储授权令牌。如需了解详情,请参阅使用 curl
  • PROJECT_ID:存储 Google Cloud 项目标识符或项目编号。
  • PROJECT_NUMBER:存储 Google Cloud 项目编号。
  • SINK_ID:接收器的名称或标识符。例如 my-sink
  • SINK_BODY:存储 TraceSink 资源的说明。TraceSink 资源包含名称和接收器目标。名称必须指定 Google Cloud 项目编号。
  • DESTINATION:存储目标的完全限定名称。这必须是一个 BigQuery 数据集。

配置目标

如需将跟踪记录导出到 BigQuery,请执行以下操作:

  1. 创建目标数据集。

  2. 使用 Cloud Trace API 或 Google Cloud CLI 创建接收器。 如需了解详情,请参阅创建接收器

  3. 为接收器授予您的 BigQuery 数据集的 dataEditor 角色:

    1. 从接收器获取写入者身份。如需了解写入者身份,请参阅接收器属性和术语

      接收器的写入者身份包含在 create 命令的响应数据中,也包含在 list 命令的响应数据中。

    2. 将接收器的写入者身份作为服务账号添加到 BigQuery 数据集中,并为其授予 BigQuery 数据修改者角色。

      • 如需使用 Google Cloud 控制台添加权限,请参阅控制对数据集的访问权限

      • 如需使用 Google Cloud CLI 添加权限,请使用 add-iam-policy-binding 命令并提供您的 Google Cloud 项目标识符和接收器的写入者身份:

        gcloud projects add-iam-policy-binding ${DESTINATION_PROJECT_ID} \
          --member serviceAccount:${WRITER_IDENTITY} \
          --role roles/bigquery.dataEditor
        

        在上一个命令中,WRITER_IDENTITY 是一个环境变量,用于存储接收器的写入者身份,DESTINATION_PROJECT_ID 是 BigQuery 数据集的 Google Cloud 项目标识符。

列出接收器

如需列出 Google Cloud 项目中的所有接收器(包括其写入者身份),请调用 traceSinks.list 方法。

gcloud

如需使用 Google Cloud CLI 列出使用默认项目定义的接收器,请运行以下命令:

gcloud alpha trace sinks list

协议

如需使用 curl 列出接收器,请将 GET 请求发送到:

https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks

例如,以下请求会检索所有接收器:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}"  https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks

显示特定接收器的详细信息

如需显示 Google Cloud 项目中特定接收器的详细信息,请调用 traceSinks.get 方法。

gcloud

如需使用 Google Cloud CLI 显示其标识符存储在 SINK_ID 中的接收器的详细信息,请运行以下命令:

gcloud alpha trace sinks describe ${SINK_ID}

协议

如需使用 curl 显示其标识符存储在 SINK_ID 中的接收器的详细信息,请将 GET 请求发送到:

https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/%{SINK_ID}

例如,以下请求会检索指定接收器的详细信息:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}"  https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/${SINK_ID}

创建接收器

如需在 Google Cloud 项目中创建接收器,请调用 traceSinks.create方法。 接收器的目标必须是 BigQuery 数据集。

此数据集必须先存在,然后您才能创建接收器。Trace 不会验证目标是否存在。如需了解如何创建 BigQuery 数据集,请参阅创建数据集

gcloud

如需使用 Google Cloud CLI 创建接收器,请运行以下命令:

gcloud alpha trace sinks create ${SINK_ID} ${DESTINATION}

协议

如需使用 curl 创建接收器,请将 POST 请求发送到:

https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks

例如,如需创建一个名为 test_sink 的接收器以使用 ${PROJECT_NUMBER} 将跟踪记录 span 导出到该项目 test_dataset中,请按如下所示定义环境变量 SINK_BODY

SINK_BODY='{"name":"projects/12345/traceSinks/test_sink","output_config":{"destination":"bigquery.googleapis.com/projects/12345/datasets/test_dataset"}}'

如需创建接收器,请运行以下命令:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}"  --header "Content-Type: application/json"  -X POST -d ${SINK_BODY} https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks

创建接收器后,可能需要几分钟时间才能将跟踪记录 span 导出到目标位置。

删除接收器

如需删除 Google Cloud 项目中的接收器,请调用 traceSinks.delete 命令。

gcloud

如需使用 Google Cloud CLI 删除其标识符存储在 SINK_ID 中的接收器,请运行以下命令:

gcloud alpha trace sinks delete ${SINK_ID}

协议

如需使用 curl 删除其标识符存储在 SINK_ID 中的接收器,请将 DELETE 请求发送到:

https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/${SINK_ID}

例如,以下请求会删除接收器:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}"  -X DELETE https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/${SINK_ID}

更新接收器

如需更新 Google Cloud 项目中的接收器,请调用 traceSinks.patch 命令。

此数据集必须先存在,然后您才能创建接收器。Trace 不会验证目标是否存在。

gcloud

如需使用 Google Cloud CLI 更新其标识符存储在 SINK_ID 中的接收器,请运行以下命令:

gcloud alpha trace sinks update ${SINK_ID} ${DESTINATION}

环境变量 DESTINATION 存储接收器的新目标位置。

协议

如需使用 curl 更新其标识符存储在 SINK_ID 中的接收器的目标,请将 PATCH 请求发送到:

https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/${SINK_ID}

例如,以下请求会更新接收器的目标:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}"  --header "Content-Type: application/json"  -X PATCH -d ${SINK_BODY} https://cloudtrace.googleapis.com/v2beta1/projects/${PROJECT_NUMBER}/traceSinks/${SINK_ID}?update_mask=output_config.destination

如需查看 SINK_BODY 的示例,请参阅创建接收器的示例。

更新接收器后,可能需要几分钟时间才能将跟踪记录 span 导出到新目标。

端到端示例

本部分介绍如何使用 Google Cloud CLI 命令列出、创建、描述、更新和删除接收器。这些命令针对项目标识符为 a-sample-project 的项目执行。此项目已预先配置为包含 2 个 BigQuery 数据集。最后,在这些示例中,接收器和目标位于同一项目中。这并不是必要条件。接收器和目标可以位于不同的 Google Cloud 项目中。

配置步骤

  1. 验证默认项目设置:

    $ gcloud config list
    

    示例响应:

    [compute]
    zone = us-east1-b
    [core]
    account = user@example.com
    disable_usage_reporting = True
    project = a-sample-project
    
    Your active configuration is: [default]
    
  2. 验证 Google Cloud CLI 版本是否至少为 274.0.0:

    $ gcloud --version
    

    示例响应:

    Google Cloud SDK 275.0.0
    alpha 2020.01.03
    beta 2020.01.03
    bq 2.0.51
    core 2020.01.03
    gsutil 4.46
    kubectl 2020.01.03
    
  3. 识别默认项目中的可用数据集:

    $ bq ls
    

    示例响应:

        datasetId
     ---------------
      dataset_1
      dataset_other
    

    请注意,首次使用 bq 命令时,您可能需要选择项目。

设置环境变量

  1. 设置 Google Cloud CLI 命令使用的环境变量:

    $ PROJECT_ID=a-sample-project
    $ PROJECT_NUMBER=123456789000
    $ SINK_ID=a-sample-sink
    $ DATA_SET_NAME=dataset_1
    $ DESTINATION=bigquery.googleapis.com/projects/${PROJECT_NUMBER}/datasets/${DATA_SET_NAME}
    

    在此示例中,目标和接收器位于同一项目中。这并不是必要条件。接收器和目标可以位于不同的 Google Cloud 项目中。

  2. 验证设置:

    $ echo $SINK_ID
    a-sample-sink
    $ echo $DATA_SET_NAME
    dataset_1
    $ echo $DESTINATION
    bigquery.googleapis.com/projects/123456789000/datasets/dataset_1
    

列出接收器

如需列出所有接收器,请运行以下命令:

$ gcloud alpha trace sinks list

由于此项目没有任何接收器,因此响应为:

Listed 0 items.

创建接收器

  1. 如需创建接收器,请运行以下命令:

    $ gcloud alpha trace sinks create ${SINK_ID} ${DESTINATION}
    

    示例响应:

    You can give permission to the service account by running the following command.
    gcloud projects add-iam-policy-binding bigquery-project \
    --member serviceAccount:export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com \
    --role roles/bigquery.dataEditor
    

    请注意,服务帐号名称包含 export-0000001cbe991a08-3434。编号 0000001cbe991a08 是 PROJECT_NUMBER 的十六位进制表示法。值 3434 是随机值。

    在执行上一个响应中的 Google Cloud CLI 之前,您必须将 bigquery-project 替换为您的项目标识符。

  2. 验证接收器是否已创建:

    $ gcloud alpha trace sinks list
    

    示例响应:

    NAME           DESTINATION                                                       WRITER_IDENTITY
    a-sample-sink  bigquery.googleapis.com/projects/123456789000/datasets/dataset_1  export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
    
  3. 详细描述接收器:

    $ gcloud alpha trace sinks describe ${SINK_ID}
    

    示例响应:

    destination: bigquery.googleapis.com/projects/123456789000/datasets/dataset_1
    name: a-sample-sink
    writer_identity: export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
    
  4. 向接收器的写入者身份授予 bigquery.dataEditor 权限。接收器创建命令会返回一个 Google Cloud CLI 命令,您可以使用该命令更新权限。

    若要成功执行此命令,请执行以下操作:

    • 确保您有修改目标位置的权限。
    • bigquery-project 替换为您的项目标识符:
    gcloud projects add-iam-policy-binding ${PROJECT_ID} --member serviceAccount:export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com --role roles/bigquery.dataEditor
    

    请注意,此示例响应中的第一个条目是接收器的写入者身份:

    Updated IAM policy for project [a-sample-project].
    bindings:
    - members:
      - serviceAccount:export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
      role: roles/bigquery.dataEditor
    - members:
      - user:user@example.com
      role: roles/cloudtrace.admin
    - members:
      - serviceAccount:service-123456789000@compute-system.iam.gserviceaccount.com
      role: roles/compute.serviceAgent
    - members:
      - serviceAccount:service-123456789000@container-engine-robot.iam.gserviceaccount.com
      role: roles/container.serviceAgent
    - members:
      - serviceAccount:service-123456789000@container-analysis.iam.gserviceaccount.com
      role: roles/containeranalysis.ServiceAgent
    - members:
      - serviceAccount:service-123456789000@containerregistry.iam.gserviceaccount.com
      role: roles/containerregistry.ServiceAgent
    - members:
      - serviceAccount:123456789000-compute@developer.gserviceaccount.com
      - serviceAccount:123456789000@cloudservices.gserviceaccount.com
      role: roles/editor
    - members:
      - user:user@example.com
      role: roles/owner
    etag: BwWbqGVnShQ=
    version: 1

更改接收器目标位置

在此示例中,目标位置从 dataset_1 更改为 dataset_other

  1. 更新环境变量 DATA_SET_NAMEDESTINATION

    $ DATA_SET_NAME=dataset_other
    $ DESTINATION=bigquery.googleapis.com/projects/${PROJECT_NUMBER}/datasets/${DATA_SET_NAME}
    $ echo ${DESTINATION}
    bigquery.googleapis.com/projects/123456789000/datasets/dataset_other
    

    请务必在修改 DATA_SET_NAMEPROJECT_NUMBER 之后刷新 DESTINATION 的值。

  2. 更改接收器目标位置:

    $ gcloud alpha trace sinks update ${SINK_ID} ${DESTINATION}
    

    示例输出如下所示:

    Updated [https://cloudtrace.googleapis.com/v2beta1/projects/123456789000/traceSinks/a-sample-sink].
    destination: bigquery.googleapis.com/projects/123456789000/datasets/dataset_other
    name: a-sample-sink
    writer_identity: export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
    

    执行 describe 命令以查看接收器的详细信息:

    $ gcloud alpha trace sinks describe ${SINK_ID}
    destination: bigquery.googleapis.com/projects/123456789000/datasets/dataset_other
    name: a-sample-sink
    writer_identity: export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
    

    更新接收器的目标位置时,您没有更改接收器写入者身份,因此无需更新接收器的权限。

删除接收器

如需删除接收器,请运行以下命令:

$ gcloud alpha trace sinks delete ${SINK_ID}

输出示例如下所示:

Really delete sink [a-sample-sink]?

Do you want to continue (y/N)? y

Deleted [https://cloudtrace.googleapis.com/v2beta1/projects/123456789000/traceSinks/a-sample-sink].

您可以通过运行 list 命令来验证结果:

$ gcloud alpha trace sinks list
Listed 0 items.

验证

您可以将 Cloud Monitoring exported_span_count 指标用作图表的依据,将 Trace 数据导出到 BigQuery 后,该图表会根据该指标显示错误。您还可以创建提醒政策,以便在出现导出错误时收到通知。

创建图表

如需使用 Metrics Explorer 查看受监控资源的指标,请执行以下操作:

  1. 在 Google Cloud 控制台的导航面板中,选择 Monitoring,然后选择  Metrics Explorer

    进入 Metrics Explorer

  2. 指标元素中,展开选择指标菜单,在过滤栏中输入 Spans Exported to BigQuery,然后使用子菜单选择一个特定资源类型和指标:
    1. 活跃资源菜单中,选择 Cloud Trace
    2. 活跃指标类别菜单中,选择 Bigquery_explort
    3. 活跃指标菜单中,选择导出到 BigQuery 的 Span
    4. 点击应用
  3. 配置数据的查看方式。
    1. Filter 元素留空。选择此选项后,图表将显示所有状态数据。
    2. 聚合元素中,将第一个菜单设置为平均值,将第二个菜单设置为状态

      这些选择会为每个唯一状态值生成单个时序。下表列出了可能的状态值:

      状态含义和纠正措施
      ok 数据转移已成功。
      bigquery_permission_denied 无法将数据导出到目标位置。导出可能会因以下任一原因而失败:
      • 跟踪记录接收器中的服务账号无权写入目标数据集。请参阅权限遭拒
      • 接收器中数据集的目标位置不存在。 请参阅无效目标位置
      • BigQuery 内部错误。这是一个意外的暂时性错误。
      bigquery_quota_exceeded BigQuery 项目已超出其 BigQuery 流式传输配额。请参阅配额已用尽
      invalid_span
      internal_errors

      invalid_destination
      阻止将数据导出到 BigQuery 时出现未知错误。如需解决此问题,请联系技术支持人员或在 Stack Overflow 上提问。 如需了解详情,请参阅获取支持

    如需详细了解如何配置图表,请参阅使用 Metrics Explorer 时选择指标

如果 Trace 接收器成功导出数据,则使用先前设置创建的图表会显示状态值为 ok 的单个时序。如果导出过程中出现错误,则图表中会显示其他时序。

创建提醒政策

如需创建提醒政策,并在将 Cloud Trace 数据导出到 BigQuery 时出错时触发,请使用以下设置。

新建条件
字段

资源和指标 资源菜单中,选择 Cloud Trace
指标类别菜单中,选择 Bigquery_export
指标菜单中,选择导出到 BigQuert 的 Span
过滤 status != ok
跨时序
时序分组依据
status
跨时序
时序聚合
sum
滚动窗口 1 m
滚动窗口函数 rate
配置提醒触发器
字段

条件类型 Threshold
提醒触发器 Any time series violates
阈值位置 Above threshold
阈值 0
重新测试窗口 1 minute

使用 curl

本部分介绍了使用 curl 工具调用 Cloud Trace API 时用到的规范和设置:

Authentication

  1. 创建环境变量以保存您的 Google Cloud 项目标识符:

    PROJECT_ID=my-project
    
  2. 创建一个环境变量以保存您的 Google Cloud 项目编号:

    PROJECT_NUMBER=12345
    
  3. 对 Google Cloud CLI 进行身份验证:

    gcloud auth login
    
  4. 设置默认 Google Cloud 项目标识符:

    gcloud config set project ${PROJECT_ID}
    
  5. 创建授权令牌并将其保存在环境变量中:

    ACCESS_TOKEN=`gcloud auth print-access-token`
    
  6. 验证访问令牌:

    echo ${ACCESS_TOKEN}
    

    命令的响应应为长字符串。例如,在一个系统上,响应的开头为:

    y29.GluiBjo....
    

调用 curl

每个 curl 命令都包含一组参数,后跟 Cloud Trace API 资源的网址。常见参数包括由 PROJECT_IDACCESS_TOKEN 环境变量指定的值。

每个 curl 调用都具有以下通用格式:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" [OTHER_ARGS]
https://cloudtrace.googleapis.com/[API_VERSION]/projects/${PROJECT_ID}/[RESOURCE]

其中:

  • [OTHER_ARGS](可选):如果您要发出 GET 请求,请忽略此字段。对于其他类型的 HTTP 请求,请将此占位符替换为请求类型以及满足请求所需的任何其他数据。
  • [API_VERSION]:指定 API 的版本。
  • [RESOURCE]:指定 Cloud Trace API 资源名称。

例如,如需列出项目中最近的 1000 个跟踪记录,请执行以下命令:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://cloudtrace.googleapis.com/v1/projects/${PROJECT_ID}/traces

问题排查

本部分包含的问题排查信息可能有助于您解决配置导出时的故障。

数据集参数无效错误

以下错误消息表示数据集名称无效:

ERROR: (gcloud.alpha.trace.sinks.create) INVALID_ARGUMENT: Request contains an invalid argument.
- '@type': type.googleapis.com/google.rpc.DebugInfo
  detail: '[ORIGINAL ERROR] generic::invalid_argument: sink destination is malformed:
    bigquery.googleapis.com/projects/123456789000/datasets/a-sample-project:dataset_1.

错误是由目标(包括作为数据集名称限定符的 Google Cloud 项目标识符 a-sample-project)造成的。

如需解决此错误,请将 a-sample-project:dataset_1 替换为 dataset_1,然后发出 create 命令。

请注意,您可以使用 bq ls 命令列出数据集。

未收到任何跟踪记录数据

有多种原因可能会导致您无法在 BigQuery 中收到跟踪记录数据。

目标位置无效

验证数据集名称和项目编号是否正确。

  • 验证数据集名称是否正确。如需列出当前项目中的数据集,请运行 bq ls

    如果您选择使用环境变量,请通过发出 echo 命令来验证每个变量的值是否正确。 例如,验证目标位置是否正确:

    $ echo ${DESTINATION}
    bigquery.googleapis.com/projects/123456789000/datasets/dataset_other
    

    由于 DESTINATION 依赖于 PROJECT_NUMBERDATA_SET_NAME 的值,因此必须先设置这两个变量。此外,如果您修改这两个变量中的任何一个,则必须刷新存储在 DESTINATION 中的值。

  • 如需确定您当前的项目编号,请运行以下命令:

    gcloud projects list --filter="${PROJECT_ID}"
    

    您可以使用以下命令以编程方式设置 PROJECT_NUMBER

    $ PROJECT_NUMBER=`gcloud projects list --filter="${PROJECT_ID}" --format="value(PROJECT_NUMBER)"`
    

权限无效

验证该服务账号是否已被授予 BigQuery 的 DataEditor 角色。您可以通过运行以下命令来验证权限:

$ gcloud projects get-iam-policy ${PROJECT_ID}

此命令的响应介绍了所有 IAM 绑定。在本例中,结果如下所示。请注意,接收器写入者身份具有 dataEditor 角色:

bindings:
- members:
  - serviceAccount:export-0000001cbe991a08-3434@gcp-sa-cloud-trace.iam.gserviceaccount.com
  role: roles/bigquery.dataEditor
- members:
  [Note, content truncated]

配额已用尽

如果您一直在接收数据但突然停止,或者您的数据不完整,则可能是您的 BigQuery 流式传输配额已用尽。 如需查看您的配额,请转到 IAM 和管理员页面,然后选择配额。 搜索 BigQuery API。有两个相关条目:每项资源每分钟的流式传输行数,每项资源每分钟的流式传输字节数。

转到“配额”

后续步骤

如需了解 BigQuery 架构,请参阅导出到 BigQuery