配置导出

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

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

术语

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

gcloud 命令行工具示例使用以下环境变量:

  • SINK_ID:接收器的名称或标识符。例如 my-sink。您无需给 gcloud 命令行工具提供完全限定的命令,因为它可以确定您的 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 或 gcloud 命令行工具创建接收器。如需了解详情,请参阅创建接收器

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

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

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

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

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

      • 如需使用 gcloud 命令行工具添加权限,请使用 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

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

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

如需使用 gcloud 命令行工具显示其标识符存储在 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

如需使用 gcloud 命令行工具创建接收器,请运行以下命令:

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

如需使用 gcloud 命令行工具删除其标识符存储在 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

如需使用 gcloud 命令行工具更新其标识符存储在 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 导出到新目标。

端到端示例

本部分演示了如何使用 gcloud 命令行工具命令列出、创建、描述、更新和删除接收器。已针对具有项目标识符 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. 验证 gcloud 命令行工具是否至少为 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. 设置 gcloud 命令行工具命令使用的环境变量:

    $ 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 是随机值。

    在上述响应中执行 gcloud 命令行工具之前,您必须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 权限。接收器 create 命令会返回一个 gcloud 命令行工具命令,您可以使用该命令来更新权限。

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

    • 确保您有修改目标位置的权限。
    • 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@gcp-sa-computescanning.iam.gserviceaccount.com
      role: roles/computescanning.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 Console 中,转到 Monitoring 或使用下面的按钮:
    转到 Monitoring
  2. 在 Monitoring 导航窗格中,点击 Metrics Explorer
  3. 确保所选标签页为指标
  4. 点击 Find resource type and metric 对应的框,然后从菜单中选择或者输入资源和指标的名称。在此文本框的各字段中填写以下信息:
    1. 输入 Cloud Trace 作为资源类型
    2. 选择 Spans Exported to BigQuery 作为指标
  5. 使用 FilterGroup ByAggregator 菜单修改数据的显示方式。 对于此图表,请使用以下设置:
    1. 过滤条件字段留空。选择此选项后,图表将显示所有状态数据。
    2. 分组依据字段选择 status。 这样会为每个唯一状态值生成一个时间序列。下表显示了可能的状态值:
      状态含义和纠正措施
      ok 数据转移已成功。
      bigquery_permission_denied 无法将数据导出到目标位置。导出可能会因以下任一原因而失败:
      • 跟踪记录接收器中的服务帐号无权写入目标数据集。请参阅权限遭拒
      • 接收器中数据集的目标位置不存在。 请参阅无效目标位置
      • BigQuery 内部错误。这是一个意外的暂时性错误。
      bigquery_quota_exceeded BigQuery 项目已超出其 BigQuery 流式传输配额。请参阅配额已用尽
      invalid_span
      internal_errors

      invalid_destination
      阻止将数据导出到 BigQuery 时出现未知错误。如需解决此问题,请联系技术支持人员或在 Stack Overflow 上提问。 如需了解详情,请参阅获取支持
    3. Aggregator 字段保留为默认值
    如需了解详情,请参阅选择指标

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

创建提醒政策

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

目标窗格
字段

Resource type Cloud Trace
Metric Spans Exported to BigQuery
Filter status != ok
Group by status
Aggregator sum
Period 1 m
Advanced Aggregation Aligner: rate
条件窗格
字段

Condition triggers if Any time series violates
Condition is above
Threshold 0
For 1 minute

使用 curl

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

身份验证

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

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

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

    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