本文將說明如何建立及管理記錄範圍,協助您有效率地找出要查看或分析的記錄項目。如果您只想查看及分析來自專案、資料夾或機構的記錄項目,這份文件就不適用於您。不過,如果您使用記錄檔接收器將記錄檔轉送至其他專案或使用者定義的記錄檔值區,或是使用記錄檔檢視畫面,這份文件中的資訊可能有助於您有效找出特定記錄檔項目。
本文件不會說明如何查看記錄。如要瞭解該主題,請參閱「使用記錄檔探索工具查看記錄檔」。
關於記錄範圍
記錄範圍是永久性的專案層級資源,會列出一系列資源。這些資源可以是專案、資料夾、機構和記錄檢視畫面。舉例來說,您可以定義記錄範圍,列出含有用於實際工作環境的資源的專案,或是列出包含特定資源類型記錄項目的記錄檢視。
建立 Google Cloud 專案、資料夾或機構資源時,記錄會建立名為 _Default
的記錄範圍。這個範圍包含建立的專案、資料夾或機構。如果搜尋的資源是 Google Cloud 專案、資料夾或機構,結果就會包含來自該資源的記錄項目,並儲存在記錄檔 bucket 中。記錄檔 bucket 可位於任何專案中。搜尋專案時,結果也會包含記錄項目,這些項目是由其他專案中的接收器轉送至專案,然後儲存在記錄檔值區。
您可以建立記錄範圍。您也可以編輯及刪除所建立的記錄範圍。不過,您無法編輯或刪除名為 _Default
的記錄範圍。
您可以使用記錄範圍控制「Logs Explorer」頁面搜尋記錄資料的資源。當您開啟該頁面並選取記錄範圍時,該頁面會搜尋該範圍中列出的資源,然後重新整理顯示畫面。
您也可以使用記錄範圍來控管記錄資訊工具搜尋記錄資料的資源。記錄檔面板是可顯示記錄檔資料的自訂資訊主頁小工具。每個記錄檔面板都有各自的設定,可讓您建立包含多個記錄檔面板的資訊主頁,每個面板都會顯示不同的記錄檔資料。詳情請參閱「在自訂資訊主頁上顯示記錄和錯誤」。
對於專案,預設記錄範圍會決定「Logs Explorer」頁面開啟時搜尋的資源組合。不過,您在搜尋資源時所設的 Identity and Access Management (IAM) 角色,以及時間範圍設定,會決定從儲存空間擷取哪些記錄項目。建立專案時,系統會將名為 _Default
的記錄範圍指定為預設記錄範圍。您可以設定預設記錄範圍。
記錄範圍與集中式記錄儲存空間的差異
集中式記錄儲存空間和記錄範圍都能讓您查看來自不同專案的記錄資料。
集中記錄儲存空間時,您會在機構或資料夾中設定接收器,將記錄項目轉送至單一儲存位置。集中式儲存空間可讓您在單一位置查詢記錄資料,因此在搜尋趨勢或調查問題時,查詢作業會變得更簡單。從安全性角度來看,您也只有一個儲存位置,可簡化安全分析人員的工作。
向記錄範圍中列出的資源發出查詢時,系統會合併個別查詢結果。記錄範圍可協助在讀取時,匯總可能儲存在不同位置的記錄資料。不過,記錄範圍也可用於提供對集中記錄資料集一或多個記錄檢視畫面的讀取權。
開啟「Logs Explorer」頁面後,系統會對預設記錄範圍中列出的資源發出查詢。因此,請設定預設範圍,讓頁面顯示您通常想查看的資料。舉例來說,您可以將預設記錄範圍設為列出記錄檢視畫面,這樣在查詢時,系統就會傳回 App Hub 應用程式的記錄資料。
最佳做法
由於記錄範圍可讓您定義及儲存設定,以供日後使用,因此建議您為複雜的搜尋設定建立記錄範圍。
舉例來說,假設您要排解問題,並想查看團隊擁有的所有虛擬機器 (VM) 執行個體的記錄項目。如要完成這項工作,您可以執行下列操作:
您判斷要查看的記錄項目儲存在多個記錄值區和多個專案中。對於大多數記錄值區,都會有記錄檢視畫面,其中包含您要分析的記錄項目。如果沒有記錄檢視,您可以建立一個。
您決定建立記錄範圍,因為您預期日後會執行類似的疑難排解工作。
您可以在 Google Cloud 控制台中開啟「Logs Explorer」頁面,然後使用「Refine scope」選單選取新的記錄範圍。
您可以查看記錄項目,找出解決調查中問題所需的資訊。
解決問題後,您會與同事分享失敗原因。您也提到,未來可能會看到類似的失敗情形,因此您建立了記錄範圍,讓您或調查失敗情形的人員,能快速找到相關的記錄項目。
App Hub 應用程式和記錄範圍
App Hub 應用程式可能會將記錄資料寫入多個專案。記錄資料可能會儲存在原始專案中,機構管理員也可能已設定集中式儲存空間。如要查看應用程式的記錄資料,請建立記錄範圍,並將其設為預設記錄範圍,然後設定記錄範圍,以便列出儲存應用程式記錄資料的專案或記錄檢視畫面。完成這些步驟後,「Logs Explorer」頁面會自動顯示應用程式寫入的資料,即使這些資料儲存在不同專案或集中記錄值區中也一樣。
在專案中建立自訂記錄範圍,以便查看記錄資料。這項專案可能是您的 App Hub 主專案,也可能是已啟用應用程式的資料夾的管理專案。舉例來說,如果資料夾的顯示名稱是 My Folder
,管理專案的顯示名稱就是 My Folder-mp
。
限制
- 您無法刪除或修改名為
_Default
的記錄範圍。 - 只有 Google Cloud 專案支援預設記錄範圍。
- 您無法將資料夾或機構新增至使用者定義的記錄範圍。
- 記錄範圍會在
global
位置建立。
事前準備
-
如要取得建立及查看記錄範圍所需的權限,以及設定預設記錄範圍,請要求管理員授予您下列 IAM 角色:
-
如要建立及查看記錄範圍,或取得預設的記錄範圍:
記錄設定寫入器 (
roles/logging.configWriter
) 在專案、資料夾或機構中 -
如要設定或取得預設記錄範圍:
可觀測性編輯器 (
roles/observability.editor
) 在專案、資料夾或機構中
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這些預先定義的角色包含建立及查看記錄範圍,以及設定預設記錄範圍所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
如要建立及查看記錄範圍,以及設定預設記錄範圍,您必須具備下列權限:
-
如要設定預設記錄範圍:
observability.scopes.{get, update}
-
如要建立及管理記錄範圍,請按照下列步驟操作:
logging.logScopes.{create, delete, get, list, update}
-
如要建立及查看記錄範圍,或取得預設的記錄範圍:
記錄設定寫入器 (
-
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Terraform
如要在本機開發環境中使用本頁面的 Terraform 範例,請先安裝並初始化 gcloud CLI,然後使用您的使用者憑證設定應用程式預設憑證。
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
詳情請參閱 Google Cloud 驗證說明文件中的「 為本機開發環境設定 ADC」。
REST
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
After installing the Google Cloud CLI, initialize it by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
詳情請參閱 Google Cloud 驗證說明文件中的「驗證以使用 REST」。
列出記錄範圍
控制台
如要列出記錄範圍,請按照下列步驟操作:
gcloud
如要列出專案中的記錄範圍,請使用
gcloud logging scopes list
指令:gcloud logging scopes list --project=PROJECT_ID
執行指令前,請先更新下列欄位:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
如要取得專案中記錄範圍的詳細資料,請使用
gcloud logging scopes describe
指令:gcloud logging scopes describe LOG_SCOPE_ID --project=PROJECT_ID
執行指令前,請先更新下列欄位:
- PROJECT_ID:專案的 ID。
- LOG_SCOPE_ID:記錄範圍的 ID。例如:
my-scope
。
Terraform
您可以使用 Terraform 建立及修改記錄範圍。不過,您無法使用 Terraform 列出記錄範圍。
REST
Cloud Logging API 包含可列出資源中記錄範圍的指令,或可回報特定記錄範圍的詳細資料。如需完整指令清單,請參閱 API 參考說明文件。
針對 Google Cloud 專案,請使用下列指令:
在先前的命令中,
parent
欄位的語法如下:projects/PROJECT_ID/locations/LOCATION_ID
上一個運算式中的欄位含義如下:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOCATION_ID 必須設為
global
。
設定預設記錄範圍
本節不適用於資料夾或機構。對於資料夾和機構,當 Logs Explorer 頁面開啟時,系統會搜尋資料夾或機構產生的記錄項目。
建立專案時,系統會建立名為
_Default
的記錄範圍。這個範圍會列出一個資源,也就是您的專案,並指定為預設記錄範圍。如果您建立專案後未修改預設記錄範圍,則「Logs Explorer」頁面會在開啟時搜尋來自專案的所有記錄項目。您可以自行建立記錄範圍,並將其指定為預設記錄範圍。這項功能可讓您設定「Logs Explorer」頁面搜尋記錄項目的資源。
控制台
如要為專案設定預設記錄範圍,請按照下列步驟操作:
-
Enable the Observability API.
啟用 Observability API 前,請確認已選取正確的專案。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
在 Google Cloud 控制台的工具列中,選取您的 Google Cloud 專案。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。。您只能為專案設定預設記錄範圍。
-
在 Google Cloud 控制台中,前往 settings「Settings」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
「設定」頁面包含多個分頁。每個分頁都會顯示特定遙測類型的範圍設定。
選取「記錄範圍」分頁標籤。
找出要指定為預設記錄範圍的記錄範圍,按一下 more_vert「More」,然後選取「Set as default」。
您選取的記錄範圍會顯示「預設」圖示
。
gcloud
如要查看及設定預設的觀測範圍,請按照下列步驟操作:
如要查看預設範圍的設定,請執行
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 name: projects/my-project/locations/global/scopes/_Default
- OBSERVABILITY_SCOPE_ID:
如要更新預設範圍,請執行
gcloud observability scopes update
指令。使用下列任何指令資料之前,請先替換以下項目:
- OBSERVABILITY_SCOPE_ID:
Scope
物件的名稱。這個值必須設為_Default
。 - LOG_SCOPE_FQN_ID:記錄範圍的完整 ID。這個欄位的格式如下:
logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/logScopes/LOG_SCOPE_ID
在上一個運算式中,LOG_SCOPE_ID 是記錄範圍的 ID。例如:
my-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\ --location=LOCATION\ --project=PROJECT_ID
Windows (PowerShell)
gcloud observability scopes update OBSERVABILITY_SCOPE_ID ` --log-scope=LOG_SCOPE_FQN_ID` --location=LOCATION` --project=PROJECT_ID
Windows (cmd.exe)
gcloud observability scopes update OBSERVABILITY_SCOPE_ID ^ --log-scope=LOG_SCOPE_FQN_ID^ --location=LOCATION^ --project=PROJECT_ID
舉例來說,如果 LOG_SCOPE_ID 的值是
my-scope
,回應會類似以下內容:Updated scope [_Default]. logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-scope name: projects/my-project/locations/global/scopes/_Default
- OBSERVABILITY_SCOPE_ID:
Terraform
您可以使用 Terraform 建立及修改記錄範圍。不過,您無法使用 Terraform 設定預設記錄範圍。
REST
如要使用 Observability API 取得或設定預設記錄範圍,請按照下列步驟操作:
確認已啟用可觀察性 API:
-
After installing the Google Cloud CLI, initialize it by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
設定 Google Cloud CLI 的預設專案:
gcloud config set project PROJECT_ID
執行上述指令前,請先取代以下內容:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
-
Enable the Observability API:
gcloud services enable observability.googleapis.com
-
執行下列其中一個步驟:
如要取得專案的預設記錄範圍,請向
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,透過參考資料頁面發出指令。舉例來說,如要取得目前的預設範圍,您可以執行下列操作:
- 按一下 [
projects.locations.scopes.get
]。 在「Try this method」小工具的「name」欄位中,輸入以下內容:
projects/PROJECT_ID/locations/global/scopes/_Default
複製前一個欄位之前,請將 PROJECT_ID 替換為專案名稱。
選取「執行」。
在授權對話方塊中,完成必要步驟。
回應如下所示:
{ "name": "projects/my-project/locations/global/scopes/_Default", "logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default" }
建立記錄範圍
每個專案最多可建立 100 個記錄範圍。記錄範圍可包含總計 100 個記錄檢視和專案,但只能包含 5 個專案。您無法將資料夾或機構新增至記錄範圍。
控制台
如要建立記錄範圍,請按照下列步驟操作:
-
在 Google Cloud 控制台中,前往 settings「Settings」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
- 在 Google Cloud 控制台的工具列中,選取專案、資料夾或機構。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- 選取「Log Scopes」分頁標籤,然後按一下「Create log scope」。
如要新增一或多個專案,請按一下「Add projects」,然後完成對話方塊。
新增專案後,您在該專案中的身分與存取權管理角色會決定您可以查看哪些記錄項目。舉例來說,您的 IAM 角色可能只允許您查看記錄值區中特定記錄檢視畫面可存取的記錄項目。如要進一步瞭解角色,請參閱「記錄角色」。
如要新增一或多個記錄檢視畫面,請按一下「Add log views」(新增記錄檢視畫面),然後完成對話方塊。
對話方塊會列出所有記錄檢視畫面,這些檢視畫面含有來自目前專案的記錄項目,或是由其他專案的接收器轉送至目前專案的記錄項目。舉例來說,如果您尚未設定任何接收器,這個對話方塊就會列出目前專案中的記錄檢視畫面。
如要列出儲存在其他 Google Cloud 專案中的記錄檢視,請按一下 add_circle「Import project」(匯入專案),然後選取 Google Cloud 專案。
新增記錄檢視畫面後,您在記錄檢視畫面或儲存記錄檢視畫面的專案中所設的 IAM 角色,會決定您可以存取哪些記錄項目。詳情請參閱「控管對記錄檢視畫面的存取權」。
在「名稱記錄範圍」部分中,輸入要顯示在「記錄範圍」分頁中的名稱和說明。
記錄範圍的名稱無法修改,且在專案中不得重複。
按一下「建立記錄範圍」。
gcloud
如要在專案中建立記錄範圍,請使用
gcloud logging scopes create
指令:gcloud logging scopes create LOG_SCOPE_ID --project=PROJECT_ID \ --description=DESCRIPTION \ --resource-names=RESOURCE_NAMES
執行指令前,請先更新下列欄位:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOG_SCOPE_ID:記錄範圍的 ID。例如:
my-scope
。 DESCRIPTION:選用。記錄範圍的說明。將說明格式調整為字串。
RESOURCE_NAMES:以半形逗號分隔的清單,列出專案或記錄檢視畫面的完整名稱。例如,如要在記錄範圍中加入
my-project
,請指定projects/my-project
。
Terraform
如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。 詳情請參閱 Terraform 供應器參考說明文件。
如要使用 Terraform 在專案、資料夾或機構中建立記錄範圍,請使用 Terraform 資源
google_logging_log_scope
。在指令中設定下列欄位:
parent
:專案、資料夾或機構的全名。例如,您可以將這個欄位設為"projects/PROJECT_ID"
,其中 PROJECT_ID 是 Google Cloud 專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。locations
:設為"global"
。name
:設為記錄範圍的完整名稱。對於專案,這個欄位的格式為:"projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE_ID"
在上述運算式中,LOG_SCOPE_ID 是記錄範圍的名稱,例如「production」。
resource_names
:專案和記錄檢視畫面的陣列,其中每個專案和記錄檢視畫面都會使用其完整修飾名稱指定。description
:簡短說明。例如「實際工作環境資源的範圍」。
REST
Cloud Logging API 也支援在資料夾或機構中建立記錄範圍。詳情請參閱 API 參考說明文件。
針對 Google Cloud 專案,請使用下列指令:
在先前的命令中,
parent
欄位的語法如下:projects/PROJECT_ID/locations/LOCATION_ID
上一個運算式中的欄位含義如下:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOCATION_ID 必須設為
global
。
修改或刪除記錄範圍
控制台
如要修改或刪除您或同事建立的記錄範圍,請按照下列步驟操作:
-
在 Google Cloud 控制台中,前往 settings「Settings」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
- 在 Google Cloud 控制台的工具列中,選取專案、資料夾或機構。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- 選取「記錄範圍」分頁標籤。
找出要修改或刪除的記錄範圍,按一下 more_vert「更多」圖示 ,然後執行下列任一操作:
- 如要修改,請選取「Edit scope」,然後完成對話方塊。
- 如要刪除,請選取「Delete scope」(刪除範圍),然後完成對話方塊。
gcloud
如要修改專案中記錄範圍內資源清單的說明,請使用
gcloud logging scopes update
指令:gcloud logging scopes update LOG_SCOPE_ID --project=PROJECT_ID \ --description=DESCRIPTION \ --resource-names=RESOURCE_NAMES
執行指令前,請先更新下列欄位:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOG_SCOPE_ID:記錄範圍的 ID。例如:
my-scope
。 DESCRIPTION:記錄範圍的說明。將說明格式調整為字串。如果不想變更記錄範圍的說明,請省略這個欄位。
RESOURCE_NAMES:以半形逗號分隔的清單,列出專案或記錄檢視畫面的完整名稱。如果您不想變更資源清單,請省略這個欄位。
如要刪除專案中的記錄範圍,請使用
gcloud logging scopes delete
指令:gcloud logging scopes delete LOG_SCOPE_ID --project=PROJECT_ID
執行指令前,請先更新下列欄位:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOG_SCOPE_ID:記錄範圍的 ID。例如:
my-scope
。
Terraform
如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。 詳情請參閱 Terraform 供應器參考說明文件。
如要使用 Terraform 修改專案、資料夾或機構中的記錄範圍,請使用 Terraform 資源
google_logging_log_scope
。REST
Cloud Logging API 包含可修改或刪除記錄範圍的指令。如需完整指令清單,請參閱 API 參考說明文件。
針對 Google Cloud 專案,請使用下列指令:
在先前的命令中,
parent
欄位的語法如下:projects/PROJECT_ID/locations/LOCATION_ID/logScopes/LOG_SCOPE_ID
上一個運算式中的欄位含義如下:
- PROJECT_ID:專案的 ID。如要設定 App Hub,請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。
- LOCATION_ID 必須設為
global
。 - LOG_SCOPE_ID:記錄範圍的 ID。例如:
my-scope
。
後續步驟
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-06-19 (世界標準時間)。
-