本页介绍了如何使用 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 项目标识符。
列出接收器
如需列出 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 项目中。
配置步骤
验证默认项目设置：
$ 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 页面：
如果您使用搜索栏查找此页面，请选择子标题为监控的结果。
- 在指标元素中，展开选择指标菜单，在过滤栏中输入
Spans Exported to BigQuery，然后使用子菜单选择一个特定资源类型和指标：- 在活动资源菜单中，选择 Cloud Trace。
- 在活跃指标类别菜单中，选择 Bigquery_explort。
- 在活跃指标菜单中，选择已导出到 BigQuery 的 Span。
- 点击应用。
- 配置数据的查看方式。
- 将 Filter 元素留空。选择此选项后，图表将显示所有状态数据。
在 Aggregation 元素中，将第一个菜单设置为 Mean， 并将第二个菜单设为 status。
这些选择会为每个唯一维度生成单个时序 状态值。下表显示了可能的状态 值：
状态值 含义和纠正措施 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。