設定匯出作業

本頁說明如何使用 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 Cloud DATASET_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,請按照下列步驟操作:

  1. 建立目的地資料集。

  2. 使用 Cloud Trace API 或 Google Cloud CLI 建立接收器。 詳情請參閱「建立接收器」一文。

  3. 為 BigQuery 資料集授予接收器 dataEditor 角色:

    1. 從接收器取得寫入者身分。如要瞭解寫入者身分,請參閱接收器屬性和術語

      接收器寫入者身分會納入建立指令的回應資料中。清單指令的回應資料中也會包含這項資訊。

    2. 將接收器的寫入者身分新增為 BigQuery 資料集的服務帳戶,並給予「BigQuery 資料編輯者」角色。

      • 如要使用 Google Cloud 控制台新增權限,請參閱控管資料集存取權

      • 如要使用 Google Cloud CLI 新增權限,請使用 add-iam-policy-binding 指令,並提供專案 ID 和接收器的寫入者身分: 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 資料集的專案 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 中),請使用 curlPATCH 要求傳送至:

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 專案中。

設定步驟

  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 替換為專案 ID。

  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 替換為專案 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

  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 指標建立圖表,顯示將追蹤資料匯出至 BigQuery 時發生的錯誤。您也可以建立快訊政策,在發生匯出錯誤時收到通知。

建立圖表

如要使用 Metrics Explorer 查看受監控資源的指標,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的 「Metrics Explorer」頁面:

    前往 Metrics Explorer

    如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果

  2. 在 Google Cloud 控制台的工具列中,選取您的 Google Cloud 專案。 如要進行 App Hub 設定,請選取 App Hub 主專案或已啟用應用程式的資料夾的管理專案。
  3. 在「指標」元素中,展開「選取指標」選單, 在篩選列中輸入 Spans Exported to BigQuery, 然後使用子選單選取特定資源類型和指標:
    1. 在「有效資源」選單中,選取「Cloud Trace」
    2. 在「Active metric categories」(使用中的指標類別) 選單中,選取「Bigquery_explort」
    3. 在「Active metrics」(有效指標) 選單中,選取「Spans Exported to BigQuery」(匯出至 BigQuery 的範圍)
    4. 按一下 [套用]
  4. 設定資料的查看方式。
    1. 將「篩選器」元素留空。選擇這個選項後,圖表會顯示所有狀態資料。
    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 時發生錯誤時接收通知,請使用下列設定。

「新條件」
「欄位」

資源和指標 在「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 時所用的慣例和設定:

驗證

  1. 建立用於儲存 Google Cloud 專案 ID 的環境變數:

    PROJECT_ID=my-project
    
  2. 建立用於儲存專案編號的環境變數: Google Cloud

    PROJECT_NUMBER=12345
    
  3. 驗證 Google Cloud CLI:

    gcloud auth login
    
  4. 設定預設 Google Cloud 專案 ID:

    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.

錯誤原因是目的地包含專案 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_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」一文。