本頁說明如何使用 Cloud Trace API 和 Google Cloud CLI 匯出追蹤記錄。您必須使用 Google Cloud CLI 274.0.0 以上版本。
如要瞭解如何更新 Google Cloud CLI,請參閱 gcloud components update
。
本頁面上的部分樣本是使用 curl
生成。如要瞭解如何設定這項工具,請參閱「使用 curl
」。
如需使用 Google Cloud CLI 指令列出、建立、說明、更新及刪除接收器的範例,請參閱端對端範例。
術語
為簡化本頁範例,我們使用了環境變數。
Google Cloud CLI 範例使用下列環境變數:
SINK_ID
:接收器的名稱或 ID。例如:my-sink
。您不需要向 Google Cloud CLI 提供完整指令,因為 CLI 可以判斷您的 Google Cloud 專案。DESTINATION
:儲存目的地的完整名稱。這必須是 BigQuery 資料集。舉例來說,有效目的地如下:bigquery.googleapis.com/projects/DESTINATION_PROJECT_NUMBER/datasets/DATASET_ID
其中
DESTINATION_PROJECT_NUMBER
是目的地的專案編號,Google CloudDATASET_ID
則是 BigQuery 資料集 ID。
curl
範例使用下列環境變數:
ACCESS_TOKEN
:儲存授權權杖。詳情請參閱「使用curl
」一文。PROJECT_ID
:儲存 Google Cloud 專案 ID 或專案編號。PROJECT_NUMBER
:儲存 Google Cloud 專案編號。SINK_ID
:接收器的名稱或 ID。例如:my-sink
。SINK_BODY
:儲存TraceSink
資源的說明。TraceSink 資源包含名稱和接收器目的地。名稱必須指定 Google Cloud 專案編號。DESTINATION
:儲存目的地的完整名稱。這必須是 BigQuery 資料集。
設定目的地
如要將追蹤記錄匯出至 BigQuery,請按照下列步驟操作:
建立目的地資料集。
使用 Cloud Trace API 或 Google Cloud CLI 建立接收器。 詳情請參閱「建立接收器」一文。
為 BigQuery 資料集授予接收器
dataEditor
角色:從接收器取得寫入者身分。如要瞭解寫入者身分,請參閱接收器屬性和術語。
接收器寫入者身分會納入建立指令的回應資料中。清單指令的回應資料中也會包含這項資訊。
將接收器的寫入者身分新增為 BigQuery 資料集的服務帳戶,並給予「BigQuery 資料編輯者」角色。
如要使用 Google Cloud 控制台新增權限,請參閱控管資料集存取權。
如要使用 Google Cloud CLI 新增權限,請使用
add-iam-policy-binding
指令,並提供專案 ID 和接收器的寫入者身分: Google Cloudgcloud projects add-iam-policy-binding ${DESTINATION_PROJECT_ID} \ --member serviceAccount:${WRITER_IDENTITY} \ --role roles/bigquery.dataEditor
在先前的指令中,
WRITER_IDENTITY
是儲存接收器寫入者身分的環境變數,而DESTINATION_PROJECT_ID
則是 BigQuery 資料集的專案 ID。 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
顯示特定接收器的詳細資料
如要顯示專案中特定接收器的詳細資料,請叫用 traceSinks.get
方法。 Google Cloud
gcloud
如要使用 Google Cloud CLI 顯示 ID 儲存在 SINK_ID
中的接收器詳細資料,請執行下列指令:
gcloud alpha trace sinks describe ${SINK_ID}
通訊協定
如要使用 curl
顯示 ID 儲存在 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
舉例來說,如要在專案 ${PROJECT_NUMBER}
中建立名為 test_sink
的接收器,將追蹤跨度匯出至 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
建立接收器後,可能需要幾分鐘時間,追蹤範圍才會匯出至目的地。
刪除接收器
如要刪除 Google Cloud 專案中的接收器,請叫用 traceSinks.delete
指令。
gcloud
如要刪除 ID 儲存在 SINK_ID
中的接收器,請使用 Google Cloud CLI 執行下列指令:
gcloud alpha trace sinks delete ${SINK_ID}
通訊協定
如要刪除 ID 儲存在 SINK_ID
中的接收器,請使用 curl
,然後將 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 doesn't verify the existence of the destination.
gcloud
如要使用 Google Cloud CLI 更新 ID 儲存在 SINK_ID
中的接收器,請執行下列指令:
gcloud alpha trace sinks update ${SINK_ID} ${DESTINATION}
環境變數 DESTINATION
會儲存接收器的新目的地。
通訊協定
如要更新接收器的目的地 (ID 儲存在 SINK_ID
中),請使用 curl
將 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
的範例,請參閱建立接收器的範例。
更新接收器後,系統可能需要幾分鐘的時間,才會將追蹤範圍匯出至新目的地。
端對端範例
本節說明如何使用 Google Cloud CLI 指令列出、建立、說明、更新及刪除接收器。這些指令是針對專案 ID 為 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
替換為專案 ID。確認接收器是否已建立:
$ 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
權限授予接收器的寫入身分。接收器建立指令會傳回 Google Cloud CLI 指令,可用於更新權限。如要順利執行這項指令,請完成下列步驟:
- 確認您有權修改目的地權限。
- 將
bigquery-project
替換為專案 ID:
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
指標建立圖表,顯示將追蹤資料匯出至 BigQuery 時發生的錯誤。您也可以建立快訊政策,在發生匯出錯誤時收到通知。
建立圖表
如要使用 Metrics Explorer 查看受監控資源的指標,請按照下列步驟操作:
-
前往 Google Cloud 控制台的 leaderboard「Metrics Explorer」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
- 在 Google Cloud 控制台的工具列中,選取您的 Google Cloud 專案。 如要進行 App Hub 設定,請選取 App Hub 主專案或已啟用應用程式的資料夾的管理專案。
- 在「指標」元素中,展開「選取指標」選單,
在篩選列中輸入
Spans Exported to BigQuery
, 然後使用子選單選取特定資源類型和指標:- 在「有效資源」選單中,選取「Cloud Trace」。
- 在「Active metric categories」(使用中的指標類別) 選單中,選取「Bigquery_explort」。
- 在「Active metrics」(有效指標) 選單中,選取「Spans Exported to BigQuery」(匯出至 BigQuery 的範圍)。
- 按一下 [套用]。
- 設定資料的查看方式。
- 將「篩選器」元素留空。選擇這個選項後,圖表會顯示所有狀態資料。
在「匯總」元素中,將第一個選單設為「平均值」, 並將第二個選單設為「狀態」。
這些選取項目會針對每個不重複的狀態值產生單一時間序列。下表列出可能的狀態值:
「狀態」值 意義和修正措施 ok
相關的資料轉移作業已順利完成。 bigquery_permission_denied
資料匯出至目的地失敗。匯出作業可能因下列原因而失敗:
bigquery_quota_exceeded
BigQuery 專案已超過 BigQuery 串流配額。請參閱「配額已用盡」。 invalid_span
internal_errors
invalid_destination
發生不明錯誤,導致資料無法匯出至 BigQuery。如要解決這個問題,請與技術支援團隊聯絡,或在 Stack Overflow 上提問。詳情請參閱「取得支援」。
如要進一步瞭解如何設定圖表,請參閱「使用 Metrics Explorer 時選取指標」。
如果 Trace 接收器成功匯出資料,使用先前設定建立的圖表會顯示單一時間序列,狀態值為 ok
。如果匯出時發生錯誤,圖表中會顯示額外的時間序列。
建立快訊政策
如要建立快訊政策,以便在將 Cloud Trace 資料匯出至 BigQuery 時發生錯誤時接收通知,請使用下列設定。
「新條件」 「欄位」 |
值 |
---|---|
資源和指標 | 在「Resources」(資源) 選單中,選取「Cloud Trace」。 在「指標類別」選單中,選取「Bigquery_export」。 在「指標」選單中,選取「匯出至 BigQuery 的 Span」。 |
篩選 | status != ok |
跨時間序列 時間序列分組依據 |
status |
跨時間序列 時間序列匯總 |
sum |
滾動視窗 | 1 m |
滾動週期函式 | rate |
設定快訊觸發條件 欄位 |
值 |
---|---|
條件類型 | Threshold |
快訊觸發條件 | Any time series violates |
門檻位置 | Above threshold |
門檻值 | 0 |
重新測試週期 | 1 minute |
使用 curl
本節說明使用 curl
工具呼叫 Cloud Trace API 時所用的慣例和設定:
驗證
建立用於儲存 Google Cloud 專案 ID 的環境變數:
PROJECT_ID=my-project
建立用於儲存專案編號的環境變數: Google Cloud
PROJECT_NUMBER=12345
驗證 Google Cloud CLI:
gcloud auth login
設定預設 Google Cloud 專案 ID:
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.
錯誤原因是目的地包含專案 ID Google Cloud,做為資料集名稱的限定符。a-sample-project
如要解決這項錯誤,請將 a-sample-project:dataset_1
替換為 dataset_1
,然後發出建立指令。
請注意,您可以使用 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」一文。