Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

排解升級 bucket 來使用 Observability Analytics 的問題

升級記錄檔 bucket 來使用 Observability Analytics，即可執行 SQL 查詢，分析儲存在該 bucket 中的記錄檔資料。如果記錄檔 bucket 升級失敗或停滯，您可以參考本文，診斷並解決同步驗證錯誤、非同步佈建錯誤和作業受阻問題。如要瞭解如何升級記錄檔 bucket，請參閱「升級 bucket 來使用 Observability Analytics」。

關於升級程序

當您發出指令，將記錄檔 bucket 升級為使用 Observability Analytics 時，Cloud Logging 會執行兩個步驟：

同步驗證：Logging 會驗證指令參數。如果驗證失敗，指令會立即傳回錯誤。
非同步佈建：如果驗證成功，Logging 會啟動長時間執行的作業，通常會在 10 分鐘內完成。

記錄檔 bucket 升級作業會受到稽核。如要查看長時間執行的作業狀態或錯誤詳情，可以使用 Operations.GetOperation 方法輪詢作業，或查詢稽核記錄。

升級期間的記錄檔 bucket 狀態

如果升級要求的同步驗證成功，Logging 會將記錄檔 bucket 的狀態從 ACTIVE 變更為 UPDATING，並啟動長時間執行的作業。作業完成後，記錄檔 bucket 的狀態會恢復為 ACTIVE。

您可以執行 gcloud logging buckets describe 指令，判斷記錄檔 bucket 的目前狀態：

gcloud logging buckets describe LOG_BUCKET_ID \
  --location=LOCATION_ID \
  --project=PROJECT_ID

執行指令前，請先替換下列項目：

PROJECT_ID：專案 ID。
LOCATION_ID：bucket 的位置。
LOG_BUCKET_ID：bucket 的 ID。

回應中的 lifecycleState 欄位會顯示 bucket 的狀態：

description: Default bucket
lifecycleState: ACTIVE
name: projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID
retentionDays: 30

在 Google Cloud 控制台中，當記錄檔 bucket 處於 UPDATING 狀態時：

在「Logs Storage」(記錄檔儲存空間) 頁面中，當長時間執行的作業處於執行中狀態時，「Observability Analytics available」(可使用 Observability Analytics) 欄會顯示「Upgrading…」(升級中…)。如果控制台無法擷取作業狀態，則會顯示「Not eligible for upgrade」(不符合升級資格)。
在「Edit bucket」(編輯 bucket) 面板和「Upgrade log bucket」(升級記錄檔 bucket) 面板中，升級 bucket 的選項會停用，工具提示則會列出「There are no pending updates」(沒有待處理的更新)，表示不符合這項條件。

VPC Service Controls perimeter 注意事項

如果 API 遭 perimeter 封鎖，或因跨專案設定，VPC Service Controls perimeter 內的記錄檔 bucket 可能無法升級。

perimeter 必須允許的 API

如要升級 VPC Service Controls perimeter 內的記錄檔 bucket，perimeter 不得限制下列服務：

logging.googleapis.com
cloudkms.googleapis.com：必須具備這項權限，才能升級使用客戶自行管理加密金鑰 (CMEK) 的記錄檔 bucket。

限制這些服務會導致下列行為：

logging.googleapis.com 受限：升級指令會立即失敗，並顯示 PERMISSION_DENIED 錯誤，記錄檔 bucket 則會維持在 ACTIVE 狀態。

解決方法：更新 perimeter，允許本節開頭列出的 API，然後重試指令。
cloudkms.googleapis.com 受限：如果是受 CMEK 保護的記錄檔 bucket，長時間執行的作業會失敗，並傳回 INTERNAL 錯誤，記錄檔 bucket 則會返回 ACTIVE 狀態。

解決方法：更新 perimeter，允許本節開頭列出的 API，然後重試指令。

跨 perimeter CMEK 設定

如果記錄檔 bucket 和 Cloud KMS 金鑰位於不同的 VPC Service Controls perimeter，您就無法使用身分型輸入或輸出規則，授予 Cloud Key Management Service 金鑰跨 perimeter 存取權。

如果輸入規則僅指定 Logging 服務帳戶身分，則會發生下列情況：

非同步佈建失敗，並顯示 INTERNAL 錯誤，記錄檔 bucket 則會返回 ACTIVE 狀態。
Cloud KMS 專案的政策稽核記錄會記錄失敗。這份稽核記錄顯示 google.cloud.kms.v1.KeyManagementService.Encrypt 方法因 NO_MATCHING_ACCESS_LEVEL 輸入違規而失敗，並指出這是 BigQuery 加密服務帳戶。

解決方法：在允許存取 Cloud KMS perimeter 的輸入規則中，將 identityType 設為 ANY_IDENTITY，並指定包含記錄檔 bucket 的專案做為來源資源：

- ingressFrom:
    identityType: ANY_IDENTITY
    sources:
    - resource: projects/PROJECT_NUMBER
  ingressTo:
    operations:
    - serviceName: cloudkms.googleapis.com
      methodSelectors:
      - method: '*'
    resources:
    - projects/KMS_PROJECT_NUMBER

在上述範例中，請替換下列項目：

PROJECT_NUMBER：記錄檔 bucket 所在專案的專案編號。
KMS_PROJECT_NUMBER：Cloud KMS 金鑰所在專案的專案編號。

如果也指定輸出規則，則必須設定 identityType: ANY_IDENTITY。

查詢稽核記錄，找出失敗資訊

本節中的查詢可協助您找出記錄項目，瞭解更新或升級記錄檔 bucket 時回報的失敗。這些查詢適用於記錄檔探索工具。

前往 Google Cloud 控制台的「Logs Explorer」頁面：

前往「Logs Explorer」(記錄檔探索工具)

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

查詢專案中所有失敗的 bucket 更新或升級作業

log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync")
severity=ERROR

如果您使用 Google Cloud 控制台，將記錄檔 bucket 升級為使用 Observability Analytics，並建立連結的 BigQuery 資料集，請使用下列查詢：

log_id("cloudaudit.googleapis.com/activity")
(protoPayload.serviceName="logging.googleapis.com" OR
 protoPayload.serviceName="bigquery.googleapis.com")
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync" OR
 protoPayload.methodName="google.cloud.bigquery.v2.DatasetService.InsertDataset")
severity=ERROR

先前查詢的結果包含記錄項目，指出連結的 BigQuery 資料集建立失敗。錯誤訊息可協助您解決失敗原因。

查詢特定 bucket 的更新或升級失敗記錄

使用下列查詢前，請先替換以下項目：

PROJECT_ID：專案 ID。
LOCATION_ID：bucket 的位置。
LOG_BUCKET_ID：bucket 的 ID。

log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync")
protoPayload.resourceName="projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID"
severity=ERROR

查詢長時間執行的作業失敗

log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync"
operation.last=true
severity=ERROR

`INVALID_ARGUMENT (3)`

INVALID_ARGUMENT (3) 錯誤代碼提供的錯誤訊息，包含足夠的資訊，可協助您解決失敗問題。因此，本節不會列出所有可能的錯誤訊息。

資源名稱問題

如要解決資源名稱問題，請以 projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID 格式傳遞有效的 bucket 資源名稱。

請確認資源名稱長度符合限制。

更新遮罩問題

如果錯誤訊息包含 update_mask 或 Update mask 文字，表示值遺漏或格式錯誤。

如要解決這個問題，請在 API 指令中指定 update_mask，並將值設為 "analytics_enabled"。

記錄檔 bucket 資格問題

您無法升級鎖定的 _Default 記錄檔 bucket 或鎖定的自訂 bucket。您可以在 _Required bucket 鎖定時升級。

如果記錄檔 bucket 已鎖定，錯誤訊息會是 "Bucket is not eligible for an upgrade to enable analytics"。

如要解決這項問題，請建立新的已啟用數據分析功能值區，並將記錄檔轉送至該值區。
您無法在對記錄檔 bucket 進行其他變更時，同時升級該 bucket。例如，您無法升級記錄檔 bucket 並更新 bucket 的說明。

如要解決這項失敗問題，請傳送個別的 UpdateBucket 或 UpdateBucketAsync 要求，其中 update_mask 僅包含 analytics_enabled，並在個別要求中更新其他記錄 bucket 欄位。
您無法升級組織、資料夾或帳單帳戶中的記錄檔 bucket。您只能升級上層為 Google Cloud 專案的記錄檔 bucket。
您無法升級已升級或正在升級的記錄檔 bucket。

使用 GetBucket 或 ListOperations 判斷升級是否已完成或正在進行。

Cloud KMS 金鑰問題

錯誤訊息：

"Not a valid key reference (wrong type): 'KMS_KEY_NAME'"
"Name "KMS_KEY_NAME" is missing the COMPONENT component. Expected the form projects/[PROJECT_ID]/locations/[ID]/keyRings/[ID]/cryptoKeys/[ID]"

解決方法：將記錄檔 bucket 的 cmek_settings.kms_key_name 更新為有效的 Cloud KMS CryptoKey 資源名稱，再升級 bucket。您必須更新資源名稱，而非金鑰版本 CryptoKeyVersion。

引數無效訊息

如果看到「"Request contains an invalid argument."」訊息，請嘗試對已啟用 CMEK 的記錄檔 bucket 執行下列操作：

確認與 bucket 的 CMEK 設定相關聯的 Logging 服務帳戶已初始化。
請確認 bucket 的保留期限為正數。

如要找出服務帳戶名稱，請更新記錄檔 bucket、位置和專案 ID，然後執行下列指令：

gcloud logging buckets describe LOG_BUCKET_ID --location=LOCATION_ID --project=PROJECT_ID

服務帳戶可能位於專案、資料夾或組織中。

`DEADLINE_EXCEEDED (4)`

使用 UpdateBucketAsync，並透過 Operations.GetOperation 方法輪詢傳回的長時間執行作業，或在背景升級完成後呼叫 GetBucket。

`NOT_FOUND (5)`

如要解決這些失敗問題，請嘗試下列做法：

請確認專案 ID 或專案編號正確無誤，且專案處於有效狀態。如果專案待刪除，請先還原專案。
確認 Logging 支援指定的位置。
確認專案中存在記錄檔 bucket ID 和位置，且目標 bucket 不是 _CloudTrace。

`PERMISSION_DENIED (7)`

權限遭拒錯誤表示不允許執行要求的動作。

缺少使用者授權

如要升級記錄檔 bucket，請確認呼叫端具備包含 logging.buckets.update 權限的 Identity and Access Management (IAM) 角色 (例如 roles/logging.configWriter 或 roles/logging.admin)，並確認沒有任何自訂組織政策會阻擋更新。

組織政策限制

如要解決 "Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: [ID]" 錯誤訊息，請確認 VPC Service Controls perimeter 未限制 logging.googleapis.com 服務。詳情請參閱「VPC Service Controls 範圍注意事項」。

區域端點問題

如要解決指定區域端點時發生的權限遭拒錯誤，請將要求傳送至全域端點 (logging.googleapis.com)，或傳送至與記錄檔 bucket 位置相符的區域端點。

`RESOURCE_EXHAUSTED (8)`

如要解決這項失敗問題，請等待進行中的佈建作業完成，然後以指數輪詢方式重試。

`FAILED_PRECONDITION (9)`

如要解決這些失敗問題，請嘗試下列做法：

確認記錄檔 bucket 處於 ACTIVE 狀態。您無法升級正在刪除、更新或佈建的記錄檔 bucket。

如要瞭解如何判斷記錄檔 bucket 的狀態，請參閱「升級期間的記錄檔 bucket 狀態」。
無法升級鎖定的記錄檔 bucket。
一般訊息 "Precondition check failed." 表示 bucket 狀態不是 ACTIVE。請等待進行中的作業完成，然後再重試升級。

`INTERNAL (13)`

錯誤訊息：

長時間執行的作業 (Operations.GetOperation)： "Failed to create analytics enabled bucket."
Cloud 稽核記錄和同步 UpdateBucket： "Internal error encountered."

解決方法：請嘗試下列做法：

如果記錄檔 bucket 已啟用 CMEK，請確認 Cloud KMS 金鑰已啟用、與 bucket 的 CMEK 設定相關聯的 Logging 服務帳戶具備金鑰的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色、BigQuery 可存取金鑰，且沒有任何組織政策或 VPC Service Controls 範圍會封鎖 Cloud KMS 存取權。

如要找出服務帳戶名稱，請執行下列指令：
```
gcloud logging buckets describe LOG_BUCKET_ID --location=LOCATION_ID --project=PROJECT_ID
```
服務帳戶可能位於專案、資料夾或組織中。
檢查 bucket (logging.views.list) 的現有記錄檔檢視，確保篩選器有效，然後重試 bucket 升級作業。
請確認記錄檔 bucket (DELETE_REQUESTED) 未遭刪除，且 bucket 未發生任何衝突的管理動作，然後再重試升級。
暫時性 BigQuery 儲存空間資料集或搜尋索引建立錯誤解決後，或下游 BigQuery、Cloud KMS 或佈建服務可用性恢復後，請重試記錄檔 bucket 升級作業。如果問題持續發生，請與 Cloud Customer Care 團隊聯絡。

`UNAVAILABLE (14)`

如果看到 "The service is currently unavailable." 訊息，請以指數輪詢方式重試 UpdateBucketAsync 要求。

排解升級 bucket 來使用 Observability Analytics 的問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。