設定多專案查詢的觀測範圍

本文說明如何在資料儲存在多項專案時，建立圖表或查看記錄資料。根據預設，只有源自專案的資料可供視覺化工具使用。不過，如果您設定範圍，視覺化和分析工具就能查詢儲存在多個專案中的資料。

如果只想監控或查看儲存在一個Google Cloud 專案中的資料，則不需執行任何設定。

範圍提供讀取時匯總功能

視覺化和分析工具可透過範圍，對儲存在多個位置的資料執行讀取時間匯總。範圍不會控管資料的儲存位置。而是依據範圍決定搜尋資料的位置。

指標和追蹤記錄資料一律會儲存在資料來源的 Google Cloud 專案中。如要在單一圖表中查看儲存在多項專案的指標資料，請設定指標範圍，列出這些專案。設定這個範圍後，當您建立圖表或警告政策時，這些服務發出的查詢會自動傳回所列專案的指標資料。追蹤記錄資料的行為也類似。

根據預設，記錄資料會儲存在資料來源的 Google Cloud 專案、帳單帳戶、資料夾或組織中。不過，您可以設定 Logging，將記錄資料從來源資源轉送至其他位置，例如其他專案或集中化記錄 bucket。無論是哪種情況，都請設定自訂記錄範圍。建議您在記錄範圍中列出記錄檢視，而非專案。記錄檢視可讓您讀取記錄 bucket 中的部分記錄項目。舉例來說，如果記錄資料儲存在三個專案中，您可以設定記錄檢視，納入每個專案的 _Default/_AllLogs 檢視。

Google Cloud Observability 如何使用範圍

Google Cloud Observability 分析和視覺化工具會依據資料類型專屬範圍，判斷要查詢哪些資源，取得工具要顯示或分析的資料。

範例：

• 「Logs Explorer」頁面開啟時，系統會查詢預設記錄範圍中列出的資源，取得記錄資料。開啟這個頁面後，您可以使用工具列選項，查詢不同範圍內的資源。
• 「Trace Explorer」頁面開啟時，系統會查詢預設追蹤記錄範圍中列出的專案，找出追蹤記錄資料。開啟這個頁面後，您可以使用工具列選項，查詢不同範圍內的資源。
• 建立警告政策時，Monitoring 會查詢指標範圍中列出的專案，取得指標資料。接著分析查詢回應，並判斷是否要建立快訊。
• 使用「Metrics Explorer」頁面建立圖表時，您需要指定要繪製圖表的指標。Monitoring 會查詢指標範圍中列出的專案，取得指標資料，然後顯示查詢結果。

Logging 和 Trace 會先驗證您在資源上的 Identity and Access Management (IAM) 角色，再傳回查詢資料。舉例來說，如果記錄範圍指定的專案，您未獲授予讀取記錄資料的權限，則對該專案執行的查詢不會傳回資料。

Monitoring 會驗證您在發出查詢的專案中的 IAM 角色。假設名為 AllEnv 的專案指標範圍列出下列專案：AllEnv、Prod 和 Staging。另外，假設您已獲得 AllEnv 專案的 Monitoring 檢視者角色。使用 AllEnv 專案時，您透過「Metrics Explorer」頁面建立的圖表會自動顯示這三個專案的指標資料。

Google Cloud Observability 範圍

本節說明 Google Cloud Observability 使用的範圍。

觀測範圍

觀測能力範圍會指定預設記錄範圍和預設追蹤記錄範圍。Logs Explorer 和Trace Explorer 等頁面會使用預設範圍，決定開啟頁面時要查詢哪些資源。舉例來說，假設您有一個應用程式，會在三個專案中產生追蹤記錄資料。您可以設定預設追蹤記錄範圍，讓「Trace Explorer」頁面自動查詢這三個專案。

如未設定觀測能力範圍，則會發生下列情況：

• 「Logs Explorer」頁面會查詢專案的記錄資料。
• 「Trace Explorer」頁面會查詢專案的追蹤記錄資料。

觀測能力範圍不適用於指標資料。

設定觀測能力範圍的時機

在下列情況下，請設定觀測能力範圍：

• 您建立自訂記錄範圍，並希望預設查詢該範圍中列出的資源。

• 您建立自訂追蹤記錄範圍，並希望預設查詢該範圍中列出的專案。

與觀測範圍相關的限制

說明	最大值
每項專案的觀測範圍數量	1

記錄範圍

Logs Explorer 頁面和顯示記錄資料的資訊主頁會使用記錄範圍：

• 「Logs Explorer」頁面開啟時，系統會自動查詢預設記錄範圍中列出的資源，取得記錄資料。這個頁面也提供控制項，可讓您切換範圍。

• 如果是資訊主頁，實作方式會決定系統要查詢專案，還是預設記錄範圍中列出的資源。

記錄範圍可以列出記錄檢視、專案、資料夾和組織。

如未設定自訂記錄範圍，Logs Explorer 頁面會查詢專案的記錄資料。

建立自訂記錄範圍的時機

為下列設定建立自訂記錄範圍：

• 將記錄資料轉送至集中化記錄值區。
• 您將記錄資料儲存在多個專案中。
• 您正在使用 Application Monitoring，這項服務會為 App Hub 應用程式產生資訊主頁。

無論是哪種情況，請設定自訂記錄範圍，列出一或多個記錄檢視。這些記錄檢視表可能位於集中式記錄 bucket，也可能位於不同的記錄 bucket。如果使用集中式記錄檔 bucket，則可建立多個自訂記錄範圍，每個範圍都有專屬的記錄檢視畫面。

如果您建立自訂記錄範圍，建議更新預設記錄範圍。

設定記錄範圍的最佳做法

• 只納入記錄檢視。
• 請勿設定同時列出專案和記錄檢視的範圍。

記錄範圍相關限制

說明	最大值
每項專案的記錄範圍數量	100
每個記錄範圍的專案數量	5
每個記錄範圍的記錄檢視或專案數量	100

詳情請參閱「建立及管理記錄範圍」。

指標範圍

Cloud Monitoring 發出的所有查詢都會使用指標範圍。舉例來說，警告政策和 Metrics Explorer 等圖表工具會向指標範圍中列出的專案發出查詢。

如未設定指標範圍，Monitoring 服務會向專案查詢指標資料。

設定指標範圍的時機

如果發生下列任一情況，請設定指標範圍：

• 您想為儲存在不同專案中的資料繪製圖表。
• 您想透過警告政策監控儲存在不同專案的資料。
• 您可以使用 App Hub 註冊應用程式。如要瞭解這種情況，請參閱「App Hub 應用程式和指標範圍」。

指標範圍相關限制

說明	最大值
每項專案的指標範圍數量	1
每個指標範圍的專案數量	375

詳情請參閱「指標範圍總覽」。

追蹤記錄範圍

「Trace Explorer」頁面會使用 Trace 範圍。開啟這個頁面時，系統會自動查詢預設追蹤記錄範圍中列出的檢視畫面，取得追蹤記錄資料。這個頁面也提供控制項，可讓您切換範圍。

如未設定自訂追蹤記錄範圍，「Trace 探索工具」頁面會查詢專案預設資料集中的 _AllSpans 檢視，取得追蹤記錄資料。

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

建立自訂追蹤範圍的時機

如果應用程式依賴不同 Google Cloud 專案中的資源，請建立自訂追蹤範圍。

設定追蹤記錄範圍的最佳做法

警告： 請確認追蹤記錄範圍中列出的所有專案，都將追蹤記錄資料儲存在相同位置。追蹤記錄資料會儲存在名為 _Trace 的觀測能力 bucket。如要瞭解如何顯示追蹤記錄資料的儲存位置，請參閱「列出觀測能力 bucket」。

追蹤記錄範圍相關限制

說明	最大值
每項專案的追蹤記錄範圍數量	100
每個追蹤記錄範圍的檢視畫面數量	20

詳情請參閱「建立及管理追蹤記錄範圍」。

設定觀測能力範圍

本節不適用於資料夾或組織。

針對記錄和追蹤資料，您在所查看專案、任何搜尋的專案和記錄檢視中的 Identity and Access Management (IAM) 角色，會影響查詢傳回的資料。如果您發出查詢來查看無權查看的記錄資料，查詢就不會傳回任何記錄資料。

設定專案的指標範圍後，專案就會獲得指標資料的讀取權限，可存取指標範圍內列出的專案所儲存的指標資料。如果使用者獲派的身分與存取權管理角色，可讓他們查看專案中的指標資料，則他們可以查看專案可用的指標資料。

如要設定觀測能力範圍，請設定預設記錄範圍和預設追蹤記錄範圍。本節其餘部分將說明如何完成這些動作。

事前準備

設定專案和 IAM 角色，並選取要使用的介面。

設定專案和角色

登入 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, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. 如要取得建立及查看範圍所需的權限，請要求管理員授予您下列 IAM 角色：

   • 如要建立及查看記錄範圍，以及取得預設記錄範圍，請在專案中具備記錄檔設定寫入者 (roles/logging.configWriter) 角色
   • 如要修改指標範圍： 專案和要新增至指標範圍的各項專案，都必須具備 Monitoring 管理員 (roles/monitoring.admin) 角色
   • 如要建立及查看追蹤記錄範圍，以及取得和設定預設範圍：專案的觀測能力範圍編輯者 (roles/observability.scopesEditor)

   如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   這些預先定義的角色具備建立及查看範圍所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

   所需權限

   必須具備下列權限，才能建立及查看範圍：

   • logging.logScopes.{create, delete, get, list, update}
   • monitoring.metricsscopes.{link, get, list}
   • observability.traceScopes.{create, delete, get, list, update}
   • observability.scopes.{get, update}

   您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

選取要使用的介面

控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，您不需要設定驗證機制。

gcloud

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

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

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. 設定預設記錄範圍：

   1. 選取「記錄範圍」分頁標籤。

      系統會列出現有的記錄範圍。標有「Default」圖示 的項目是預設記錄範圍。如要建立記錄範圍，請按一下「Create log scope」(建立記錄範圍)，然後完成對話方塊。詳情請參閱「建立及管理記錄範圍」。

   2. 找出要設為預設值的項目，按一下「更多」圖示，然後選取「設為預設值」。

4. 設定指標範圍：

   1. 選取「Metrics scope」(指標範圍) 分頁標籤。
   2. 在「Google Cloud Projects」(Google Cloud 雲端專案) 窗格中，按一下「Add Projects」(新增專案)，然後完成對話方塊。詳情請參閱「設定指標範圍」。

5. 設定預設追蹤記錄範圍：

   1. 選取「Trace Scopes」(追蹤範圍) 分頁標籤，然後執行下列操作：

      系統會列出現有的追蹤記錄範圍。含有「Default」圖示 的項目是預設追蹤記錄範圍。如要建立追蹤記錄範圍，請按一下「Create log scope」(建立記錄範圍)，然後完成對話方塊。詳情請參閱「建立及管理追蹤記錄範圍」。

   2. 找出要設為預設值的項目，按一下「更多」圖示，然後選取「設為預設值」。

gcloud

如要查看及更新觀測能力範圍，請按照下列步驟操作：

1. 如要查看觀測能力範圍的設定，請執行 gcloud observability scopes describe 指令。

   使用下列任何指令資料前，請先替換以下項目：

   • OBSERVABILITY_SCOPE_ID：Scope 物件的名稱。這個值必須設為 _Default。
   • LOCATION：位置欄位必須設為 global。
   • PROJECT_ID：專案 ID。

   執行 gcloud observability scopes describe 指令：

   Linux、macOS 或 Cloud Shell

   gcloud observability scopes describe OBSERVABILITY_SCOPE_ID \
      --location=LOCATION\
      --project=PROJECT_ID

   Windows (PowerShell)

   gcloud observability scopes describe OBSERVABILITY_SCOPE_ID `
      --location=LOCATION`
      --project=PROJECT_ID

   Windows (cmd.exe)

   gcloud observability scopes describe OBSERVABILITY_SCOPE_ID ^
      --location=LOCATION^
      --project=PROJECT_ID

   指令的回應大致如下：

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

2. 如要更新觀測能力範圍，請執行 gcloud observability scopes update 指令。在 update 指令中，您可以加入 --log-scope 旗標、--trace-scope 旗標，或同時加入這兩個旗標。

   使用下列任何指令資料前，請先替換以下項目：

   • OBSERVABILITY_SCOPE_ID：Scope 物件的名稱。這個值必須設為 _Default。
   • LOG_SCOPE_FQN_ID：記錄範圍的完整資源名稱。這個欄位的格式如下：

     logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/logScopes/LOG_SCOPE_ID

     在上述運算式中，LOG_SCOPE_ID 是記錄範圍的 ID。例如：my-scope。

   • TRACE_SCOPE_FQN_ID：追蹤記錄範圍的完整資源名稱。這個欄位的格式如下：

     projects/PROJECT_ID/locations/LOCATION/traceScopes/TRACE_SCOPE_NAME

     在上述運算式中，TRACE_SCOPE_NAME 是追蹤記錄範圍的名稱。例如：my-trace-scope。

   • LOCATION：位置欄位必須設為 global。
   • PROJECT_ID：專案 ID。

   執行 gcloud observability scopes update 指令：

   Linux、macOS 或 Cloud Shell

   gcloud observability scopes update OBSERVABILITY_SCOPE_ID \
      --log-scope=LOG_SCOPE_FQN_ID\
      --trace-scope=TRACE_SCOPE_FQN_ID\
      --location=LOCATION\
      --project=PROJECT_ID

   Windows (PowerShell)

   gcloud observability scopes update OBSERVABILITY_SCOPE_ID `
      --log-scope=LOG_SCOPE_FQN_ID`
      --trace-scope=TRACE_SCOPE_FQN_ID`
      --location=LOCATION`
      --project=PROJECT_ID

   Windows (cmd.exe)

   gcloud observability scopes update OBSERVABILITY_SCOPE_ID ^
      --log-scope=LOG_SCOPE_FQN_ID^
      --trace-scope=TRACE_SCOPE_FQN_ID^
      --location=LOCATION^
      --project=PROJECT_ID

   舉例來說，如果 LOG_SCOPE_ID 的值為 my-log-scope，TRACE_SCOPE_NAME 的值為 my-trace-scope，則回應會類似下列內容：

   Updated scope [_Default].
   logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-log-scope
   traceScope: projects/my-project/locations/global/traceScopes/my-trace-scope
   name: projects/my-project/locations/global/scopes/_Default
   

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"
       }
       

進一步瞭解範圍

如要進一步瞭解範圍，請參閱下列文件：

• 建立及管理記錄範圍。
• 指標範圍總覽。
• 建立及管理追蹤記錄範圍。