建立及管理追蹤記錄範圍

本文說明如何建立及管理追蹤記錄範圍，讓「Trace 探索工具」頁面找出您想查看或分析的追蹤記錄範圍。如果您只想查看及分析源自 Google Cloud 專案的範圍，則不需要設定任何追蹤範圍。不過，如果您的追蹤資料儲存在多個專案中 (使用微服務架構時可能會發生這種情況)，您需要執行一些設定活動，才能從單一 Google Cloud 專案查看所有時距。

本文不會說明如何查看追蹤記錄和範圍。 如要瞭解該主題，請參閱「尋找及探索追蹤記錄」。

這項功能僅支援 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。

關於追蹤記錄範圍

追蹤記錄範圍是專案層級的永久資源，會列出檢視區塊，方便您存取追蹤記錄資料。您可以設定「Trace 探索工具」頁面，依追蹤記錄範圍進行搜尋，也就是說，該頁面會搜尋所選範圍中列出的檢視畫面。系統會根據您在搜尋檢視畫面中的 Identity and Access Management (IAM) 角色和時間範圍設定，從儲存空間擷取資料並顯示。

您可以建立追蹤範圍，也可以修改及刪除您建立的任何追蹤範圍。如果服務會將 span 資料寫入多個 Google Cloud 專案，您就可以建立追蹤記錄範圍。

追蹤記錄範圍會列出檢視區塊，而非 Google Cloud 專案。雖然您在設定追蹤範圍時會選取專案，但系統會將這些專案的預設追蹤記錄檢視畫面新增至範圍。專案的預設追蹤記錄檢視畫面對應至路徑為 _Trace/Spans/_AllSpans 的檢視畫面，其中 _Trace、Spans 和 _AllSpans 欄位是指觀測功能 bucket、資料集和檢視畫面。資料集 Spans 會儲存追蹤資料。

除非您使用包含追蹤記錄範圍或追蹤記錄和時距 ID 的網址開啟「Trace 探索工具」頁面，「Trace 探索工具」頁面會搜尋預設追蹤記錄範圍中列出的檢視畫面，找出追蹤記錄資料。建立專案時，系統會將名為 _Default 的追蹤範圍設為預設追蹤範圍。不過，您可以選取其他追蹤記錄範圍，做為預設追蹤記錄範圍。

關於觀測範圍

觀測範圍會指定開啟對應的探索工具頁面時，要使用哪些追蹤記錄範圍和記錄範圍。如果您未設定可觀測範圍，列出儲存資料的資源，可能就無法關聯追蹤記錄和記錄檔資料。詳情請參閱「設定多專案查詢的可觀測性範圍」。

App Hub 應用程式和追蹤範圍

您的 App Hub 應用程式可能會將追蹤資料寫入多個專案。如要取得這類資料的匯總檢視畫面，請建立追蹤記錄範圍，將其設為列出所有儲存追蹤記錄資料的專案預設追蹤記錄檢視畫面，然後將其設為預設追蹤記錄範圍。完成這些步驟後，「追蹤記錄探索工具」頁面就會自動顯示應用程式寫入的資料，即使這些資料儲存在不同專案中也沒問題。

在要查看追蹤記錄資料的專案中，建立自訂追蹤記錄範圍。這個專案是您的 App Hub 主專案或管理專案。舉例來說，如果資料夾的顯示名稱為「My Folder」，則資料夾管理專案的顯示名稱為「My Folder-mp」。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. 如要取得建立及查看追蹤範圍所需的權限，請要求管理員授予您專案的「Observability 範圍編輯者」 (roles/observability.scopesEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

   「可觀測性範圍編輯者」角色包含私密權限，可供您建立及查看追蹤範圍。這些權限無法納入自訂 IAM 角色。

2. 選取這個頁面上的分頁，瞭解如何使用範例：

   控制台

   使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

   gcloud

   在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

   Terraform

   如要在本頁的本機開發環境中使用 Terraform 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

   1. 安裝 Google Cloud CLI。

   2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

   3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證：

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

   詳情請參閱 Google Cloud 驗證說明文件中的「 為本機開發環境設定 ADC」。

   REST

   如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

   安裝 Google Cloud CLI。

   若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

   詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

列出追蹤記錄範圍

控制台

如要列出追蹤範圍，請執行下列操作：

1. 前往 Google Cloud 控制台的「Settings」(設定) 頁面 ：

   前往「設定」

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

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

3. 選取「追蹤範圍」分頁標籤。

   視窗會顯示追蹤範圍清單。 包含「預設」圖示 的項目是預設追蹤範圍。

4. 如要查看追蹤範圍的詳細資料，請展開該範圍。

   展開追蹤記錄範圍後，即可查看該範圍包含的檢視清單。每列都會列出專案 ID，以及類似 _Trace/Spans/_AllSpans 的項目，用於識別追蹤資料的預設儲存位置。_Trace、Spans 和 _AllSpans 欄位是指追蹤記錄資料的觀測 bucket、資料集和檢視畫面。_AllSpans 檢視畫面會對應至 bucket 中的每個項目：

   名稱	說明	類型	資源
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

不支援。

Terraform

您可以使用 Terraform 建立及修改追蹤範圍。不過，您無法使用 Terraform 列出追蹤範圍。

REST

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要列出 Google Cloud 專案中的所有追蹤範圍，請使用 projects.locations.traceScopes.list 指令。您必須指定路徑參數。

這個端點的路徑參數語法如下：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

上述運算式中的欄位具有下列意義：

• PROJECT_ID：專案的 ID。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。
• LOCATION_ID 必須設為 global。

回應是 TraceScope 物件的陣列。每個物件都包含名稱和資源清單。

如要取得特定追蹤範圍的相關資訊，請使用 projects.locations.traceScopes.get 指令。

建立追蹤記錄範圍

「Trace 探索工具」頁面顯示的時距取決於搜尋的檢視畫面、您在這些檢視畫面中的 IAM 角色、時間範圍設定，以及您套用的篩選器。

警告： 請確保追蹤範圍中列出的所有檢視區塊，都將追蹤記錄資料儲存在相同位置。系統會將追蹤資料儲存在名為 _Trace 的可觀測性 bucket 中。如要瞭解如何顯示追蹤記錄資料的儲存位置，請參閱「列出可觀測性 bucket」一文。

每個專案最多可建立 100 個追蹤範圍。追蹤記錄範圍最多可包含 20 個檢視畫面。

控制台

如要建立追蹤範圍，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Settings」(設定) 頁面 ：

   前往「設定」

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

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
3. 選取「追蹤範圍」分頁標籤，然後按一下「建立追蹤範圍」。

4. 按一下「新增專案」並完成對話方塊。

   注意： 選取專案後，系統會將專案的預設追蹤記錄檢視畫面新增至範圍。

5. 在「Name trace scope」(命名追蹤範圍) 部分，輸入要顯示在「Trace Scopes」(追蹤範圍) 分頁中的名稱和說明。

   追蹤記錄範圍名稱無法修改，且在專案中不得重複。

6. 按一下「建立追蹤範圍」。

   根據預設，「追蹤範圍」表格會以摺疊形式列出追蹤範圍。表格會列出每個範圍的名稱、說明、類型和資源數量。

   展開追蹤記錄範圍後，即可查看該範圍包含的檢視清單。每列都會列出專案 ID，以及類似 _Trace/Spans/_AllSpans 的項目，用於識別追蹤資料的預設儲存位置。_Trace、Spans 和 _AllSpans 欄位是指追蹤記錄資料的觀測 bucket、資料集和檢視畫面。_AllSpans 檢視畫面會對應至 bucket 中的每個項目：

   名稱	說明	類型	資源
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

不支援。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如要使用 Terraform 在專案中建立追蹤範圍，請按照下列步驟操作：

1. 使用 Terraform 資源 google_observability_trace_scope。

   在指令中，設定下列欄位：

   • project：專案、資料夾或機構的名稱。 例如，my-project。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。

     注意： 選取專案後，系統會顯示該專案的 Spans 資料集 _AllSpans 檢視畫面。系統會將 _AllSpans 檢視區塊新增至範圍。

   • provider：設為 google-beta。

   • trace_scope_id：設為範圍 ID。例如：my-trace-scope。

   • location：設為 "global"。

   • resource_names：專案陣列，每個專案都使用完整名稱指定。

   • description：簡短說明。例如「Scope for production resources」。

2. 更新 main.tf 檔案後，請升級 Terraform 安裝版本：

   terraform -init upgrade
   

   由於資源為Beta 版，因此必須升級。google_observability_trace_scope

REST

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要建立追蹤範圍，請使用 projects.locations.traceScopes.create 指令。您必須指定路徑參數，並提供 TraceScope 物件。回應為 TraceScope 物件。

這個端點的路徑參數語法如下：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

上述運算式中的欄位具有下列意義：

• PROJECT_ID：專案的 ID。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。
• LOCATION_ID 必須設為 global。

修改或刪除追蹤範圍

您無法刪除或修改名為 _Default 的追蹤記錄範圍。您可以修改或刪除所有其他追蹤範圍。

控制台

如要修改或刪除追蹤範圍，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Settings」(設定) 頁面 ：

   前往「設定」

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

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
3. 選取「追蹤範圍」分頁標籤。

4. 找出要修改或刪除的追蹤範圍， 按一下「更多」，然後執行下列其中一項操作：

   • 如要修改，請選取「編輯範圍」，然後完成對話方塊。
   • 如要刪除範圍，請選取「刪除範圍」，然後完成對話方塊。

gcloud

不支援。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如要使用 Terraform 修改專案中的追蹤範圍，請執行下列步驟：

1. 使用 Terraform 資源 google_observability_trace_scope。

2. 更新 main.tf 檔案後，請升級 Terraform 安裝版本：

   terraform -init upgrade
   

   由於資源為Beta 版，因此必須升級。google_observability_trace_scope

REST

修改範圍

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要修改追蹤範圍，請使用 projects.locations.traceScopes.patch 指令。您必須指定路徑參數、查詢參數，並提供 TraceScope 物件。查詢參數會指出變更的欄位。回應為 TraceScope 物件。

這個端點的路徑參數語法如下：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

上述運算式中的欄位具有下列意義：

• PROJECT_ID：專案的 ID。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。
• LOCATION_ID 必須設為 global。
• TRACE_SCOPE_NAME：追蹤記錄範圍的名稱。例如：my-trace-scope。

刪除範圍

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要刪除追蹤範圍，請使用 projects.locations.traceScopes.delete 指令。您必須指定路徑參數。

這個端點的路徑參數語法如下：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

上述運算式中的欄位具有下列意義：

• PROJECT_ID：專案的 ID。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。
• LOCATION_ID 必須設為 global。
• TRACE_SCOPE_NAME：追蹤記錄範圍的名稱。例如：my-trace-scope。

設定預設追蹤記錄範圍

「Trace 探索工具」頁面開啟時，會搜尋預設追蹤記錄範圍中列出的檢視畫面，找出追蹤記錄資料。如果無法存取該追蹤記錄範圍，則「Trace 探索工具」頁面會查詢預設資料集中的專案 _AllSpans 檢視畫面。

建立專案時，系統會建立名為 _Default 的追蹤記錄範圍，並將其指定為預設追蹤記錄範圍。不過，您可以建立自己的追蹤範圍，並指定為預設追蹤範圍。

控制台

如要設定預設追蹤記錄範圍，請執行下列操作：

1. 前往 Google Cloud 控制台的「Settings」(設定) 頁面 ：

   前往「設定」

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

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

3. 選取「追蹤範圍」分頁標籤。

   這個分頁會顯示追蹤範圍，並包含建立自訂追蹤範圍的按鈕。以「預設」圖示 顯示的追蹤記錄範圍，就是目前的預設追蹤記錄範圍。

4. 如要變更預設追蹤範圍，請找出要設為預設追蹤範圍的追蹤範圍，按一下「更多」，然後選取「設為預設值」。

   您選取的追蹤範圍會顯示「預設」圖示 。

gcloud

不支援。

Terraform

您可以使用 Terraform 建立及修改追蹤範圍。不過，您無法使用 Terraform 設定預設追蹤記錄範圍。

REST

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要透過 API 呼叫取得及設定預設記錄範圍或預設追蹤範圍，請設定可觀測性範圍。可觀測性範圍會列出預設記錄範圍和預設追蹤記錄範圍：

• 如要取得專案的預設可觀測範圍，請向 projects.locations.scopes.get 端點傳送要求。您必須指定路徑參數。回應是 Scope 物件，其中列出預設記錄範圍和預設追蹤範圍。

• 如要更新專案的預設可觀測範圍，請向 projects.locations.scopes.patch 端點傳送要求。您必須指定路徑參數、查詢參數，並提供 Scope 物件。查詢參數會指出變更的欄位。回應為 Scope 物件。

兩個端點的路徑參數格式如下：

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

上述運算式中的欄位具有下列意義：

• PROJECT_ID：專案的 ID。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。
• LOCATION：位置欄位必須設為 global。
• OBSERVABILITY_SCOPE_ID：Scope 物件的名稱。這個欄位必須設為 _Default。系統會自動建立名為 _Default 的 Scope 物件，用於儲存預設記錄範圍和預設追蹤範圍的相關資訊。

如要將指令傳送至 API 端點，可以使用 APIs Explorer，從參考頁面發出指令。舉例來說，如要取得目前的預設範圍，可以執行下列操作：

1. 按一下 [projects.locations.scopes.get]。

2. 在「Try this method」(試用這個方法) 小工具的「name」(名稱) 欄位中，輸入下列內容：

   projects/PROJECT_ID/locations/global/scopes/_Default
   

   複製上一個欄位之前，請先將 PROJECT_ID 換成專案名稱。

3. 選取「執行」。

4. 在授權對話方塊中，完成必要步驟。

   回覆內容大致如下：

   {
   "name": "projects/my-project/locations/global/scopes/_Default",
   "logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
   "traceScope": "projects/my-project/locations/global/traceScopes/_Default"
   }
   

追蹤記錄範圍限制

追蹤記錄範圍限制	值
每個專案的追蹤記錄範圍數量上限	100
每個追蹤範圍的檢視畫面數量上限	20

後續步驟

• 尋找及探索追蹤記錄

• Cloud Logging 和 Cloud Monitoring 包含類似的建構函式，可讓您控管可查看或監控的記錄資料或指標資料。如要瞭解這些範圍，請參閱下列文件：

  • 觀測範圍總覽
  • 建立及管理記錄範圍
  • 指標範圍總覽