本页介绍了如何使用 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，请执行以下操作：
创建目标数据集。
使用 Cloud Trace API 或 Google Cloud CLI 创建接收器。如需了解详情，请参阅创建接收器。
为接收器授予您的 BigQuery 数据集的
dataEditor角色：从接收器中获取写入者身份。如需了解写入者身份，请参阅接收器属性和术语。
接收器的写入者身份包含在 create 命令的响应数据中，也包含在 list 命令的响应数据中。
将接收器的写入者身份作为服务账号添加到 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 项目标识符。
列出接收器
如需列出项目中的所有接收器（包括其写入者身份），请调用 traceSinks.list 方法。 Google Cloud
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}
更新接收器
如需更新项目中的接收器，请调用 traceSinks.patch 命令。 Google Cloud
此数据集必须先存在，然后您才能创建接收器。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 项目中。
配置步骤
验证默认项目设置：
$ 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]
验证 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
识别默认项目中的可用数据集：
$ bq ls示例响应：
datasetId --------------- dataset_1 dataset_other请注意，首次使用
bq命令时，您可能需要选择项目。
设置环境变量
设置 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 项目中。
验证设置：
$ 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.
创建接收器
如需创建接收器，请运行以下命令：
$ 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替换为您的项目标识符。验证接收器是否已创建：
$ 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
详细描述接收器：
$ 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
向接收器的写入者身份授予
bigquery.dataEditor权限。接收器 create 命令会返回一个 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：
更新环境变量
DATA_SET_NAME和DESTINATION：$ 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_NAME或PROJECT_NUMBER之后刷新DESTINATION的值。更改接收器目标位置：
$ 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 查看受监控资源的指标，请执行以下操作：
-
在 Google Cloud 控制台中，转到 leaderboard Metrics Explorer 页面：
如果您使用搜索栏查找此页面，请选择子标题为监控的结果。
- 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。
- 在指标元素中，展开选择指标菜单，在过滤栏中输入
Spans Exported to BigQuery，然后使用子菜单选择一个特定资源类型和指标：- 在活跃资源菜单中，选择 Cloud Trace。
- 在活跃指标类别菜单中，选择 Bigquery_explort。
- 在活跃指标菜单中，选择 Spans Exported to BigQuery。
- 点击应用。
- 配置数据的查看方式。
- 将过滤条件元素留空。选择此选项后，图表将显示所有状态数据。
在汇总元素中，将第一个菜单设置为平均值，将第二个菜单设置为状态。
这样会为每个唯一状态值生成一个时序。下表显示了可能的状态值：
状态值 含义和纠正措施 ok数据转移已成功。 bigquery_permission_denied无法将数据导出到目标位置。导出可能会因以下任一原因而失败：
bigquery_quota_exceededBigQuery 项目已超出其 BigQuery 流式传输配额。请参阅配额已用尽。 invalid_span
internal_errors
invalid_destination阻止将数据导出到 BigQuery 时出现未知错误。如需解决此问题，请联系技术支持人员或在 Stack Overflow 上提问。 如需了解详情，请参阅获取支持。
如需详细了解如何配置图表，请参阅使用 Metrics Explorer 时选择指标。
如果您的 Trace 接收器成功导出数据，则使用先前设置创建的图表将显示一个状态值为 ok 的时序。如果导出过程中出现错误，则图表中会显示其他时间序列。
创建提醒政策
如需创建一项提醒政策，以便在将 Cloud Trace 数据导出到 BigQuery 时出错时触发，请使用以下设置。
| 新建条件 字段 |
值 |
|---|---|
| 资源和指标 | 在资源菜单中，选择 Cloud Trace。 在指标类别菜单中，选择 Bigquery_export。 在指标菜单中，选择 Spans Exported to BigQuert。 |
| 过滤 | status != ok |
| 跨时间序列 时间序列分组依据 |
status |
| 跨时间序列 时间序列聚合 |
sum |
| 滚动窗口 | 1 m |
| 滚动窗口函数 | rate |
| 配置提醒触发器 字段 |
值 |
|---|---|
| 条件类型 | Threshold |
| 提醒触发器 | Any time series violates |
| 阈值位置 | Above threshold |
| 阈值 | 0 |
| 重新测试窗口 | 1 minute |
使用 curl
本部分介绍了使用 curl 工具调用 Cloud Trace API 时用到的规范和设置：
身份验证
创建一个环境变量来保存您的 Google Cloud 项目标识符：
PROJECT_ID=my-project
创建一个环境变量来保存您的 Google Cloud 项目编号：
PROJECT_NUMBER=12345
为 Google Cloud CLI 进行身份验证：
gcloud auth login
设置默认 Google Cloud 项目标识符：
gcloud config set project ${PROJECT_ID}创建授权令牌并将其保存在环境变量中：
ACCESS_TOKEN=`gcloud auth print-access-token`
验证访问令牌：
echo ${ACCESS_TOKEN}命令的响应应为长字符串。例如，在一个系统上，响应的开头为：
y29.GluiBjo....
调用 curl
每个 curl 命令都包含一组参数，后跟 Cloud Trace API 资源的网址。常见参数包括由 PROJECT_ID 和 ACCESS_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_NUMBER和DATA_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。