排解記錄代理程式相關問題

本頁說明如何疑難排解 Logging 代理程式在安裝或互動時遇到的常見問題。

檢查清單

如果您在安裝或使用 Logging 代理程式時遇到問題，請檢查以下項目：

• 如果 Linux 安裝指令產生錯誤，請檢查您的安裝指令前置字元是否為 sudo。

• 確認代理程式服務正在您的 VM 執行個體上執行：

  • 針對 Windows VM，請使用下列 PowerShell 指令：

    Get-Service -Name StackdriverLogging
    

    搜尋名稱為 Stackdriver Logging 的服務。如果代理程式未執行，您可能需要重新啟動代理程式。

  • 針對 Linux VM，請使用下列指令：

    sudo service google-fluentd status
    

    如果代理程式未執行，您可能需要使用以下指令來重新啟動代理程式：

    sudo service google-fluentd restart
    

    如果重新啟動失敗，且記錄輸出顯示為「Disabled via metadata」(已透過中繼資料停用)，代表您可能正在執行來自 Google Cloud Marketplace 的映像檔，其中 Logging 代理程式預設為停用。google-logging-enable 執行個體中繼資料鍵會控制記錄代理程式啟用狀態，如果值為 0，則會停用代理程式。如要重新啟用代理程式，請移除 google-logging-enable 鍵，或將其值設為 1。詳情請參閱建立已停用記錄代理程式的執行個體。

    如果代理程式未透過中繼資料停用，請重新安裝代理程式。請參閱下方的「重新安裝 Logging 代理程式」一節。

• 查看代理程式是否已將錯誤訊息寫入記錄。

  • 在 Windows 的版本 v1-9 上，記錄代理程式會將其記錄儲存於 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log。

    您無法取得代理程式的先前版本。

  • 在 Linux 上，記錄代理程式是 fluentd 套件，會將訊息記錄到 /var/log/google-fluentd/google-fluentd.log：

    • 如果您看到 HTTP 429 錯誤，表示您可能已經超過了 Logging API 配額。您可以在 Google Cloud 控制台中依序選取「API 和服務」>「資訊主頁」，查看可用配額。選擇 Logging API。

    • 如果您看到 API 存取權或授權問題，請前往驗證 Compute Engine 憑證。

• 如果代理程式似乎正常執行，但您未取得任何資料，請您檢查代理程式是否將資料傳送至正確專案。請參閱下方的驗證 Compute Engine 憑證一節。

• 如果代理人無法授權，請檢查私密金鑰的憑證是否缺少或無效。

驗證代理程式安裝

如要確認安裝是否成功，請在記錄檔探索工具中尋找代理程式的測試記錄項目。

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

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

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

2. 在頁面頂端，選擇包含 VM 執行個體的專案：

   • 針對 Compute Engine VM 執行個體，選擇包含 VM 執行個體的 Google Cloud 專案。
   • 針對 Amazon EC2 VM 執行個體，選擇您要傳送記錄檔的 Google Cloud 專案。

3. 在視窗分頁中，為 VM 執行個體選擇資源：

   • 針對 Compute Engine，選擇 「GCE VM 執行個體」。
   • 針對 Amazon EC2，選擇 [AWS EC2 執行個體]。
   • 選取 [syslog] (Linux)、[fluent.info] (Windows) 或 [所有記錄]。

如果您看到「Successfully sent gRPC to Logging API」(已成功將 gRPC 傳送至 Logging API) 的記錄項目，表示代理程式安裝作業已完成。這則訊息會在安裝代理程式後，以及每次重新啟動代理程式時產生。

如要進一步瞭解記錄檔探索工具，請參閱「使用記錄檔探索工具」。

測試代理程式

如果您懷疑代理程式無法運作，請確認代理程式是否正在執行，然後嘗試傳送測試訊息至記錄：

找出測試訊息

傳送測試訊息後，請在記錄檔探索工具中查看：

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

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

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

2. 在頁面頂端，選擇包含 VM 執行個體的專案：

   • 針對 Compute Engine VM 執行個體，選擇包含 VM 執行個體的 Google Cloud 專案。
   • 針對 Amazon EC2 VM 執行個體，選擇您要傳送記錄檔的 Google Cloud 專案。

3. 在視窗分頁中，為 VM 執行個體選擇資源：

   • 針對 Compute Engine，選擇 「GCE VM 執行個體」。
   • 針對 Amazon EC2，選擇 [AWS EC2 執行個體]。
   • 選取 [syslog] (Linux)、[fluent.info] (Windows) 或 [所有記錄]。

4. 您應該會看到包含測試訊息的記錄項目。如果是這樣，則表示 Logging 代理程式已經正常運作。

驗證 Compute Engine 憑證

為了讓 Compute Engine VM 執行個體能夠在沒有私密金鑰憑證的情況下執行代理程式，執行個體必須擁有適當的存取權範圍，且執行個體使用的服務帳戶身分必須擁有適當的 IAM 權限。

建立 VM 執行個體時，預設範圍與服務帳戶設定已足以執行代理程式。非常舊的執行個體，或者您已變更其預設設定的執行個體，可能沒有適當的憑證。

無法載入預設憑證

如果記錄記錄檔中出現 Could not load the default credentials 失敗，表示代理程式可能無法連線至 Compute Engine 中繼資料伺服器。

錯誤記錄如下所示：

Starting google-fluentd 1.8.4: /opt/google-fluentd/embedded/lib/ruby/gems/2.6.0/gems/googleauth-0.9.0/lib/googleauth/application_default.rb:74:in `get_application_default': Could not load the default credentials. Browse to (RuntimeError) https://developers.google.com/accounts/docs/application-default-credentials for more information.

這可能是因為 VM 有自訂 Proxy 設定。如要修正這個問題，請參閱Proxy 設定操作說明，將 Compute Engine 中繼資料伺服器 (metadata.google.internal 或 169.254.169.254) 排除在 Proxy 之外。如果錯誤持續發生，請從 VM 中移除預設的 Compute Engine 服務帳戶，然後重新新增。

驗證存取權範圍

如要驗證存取權範圍，請執行下列操作：

1. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面：

   前往「VM instances」(VM 執行個體) 頁面

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

2. 按一下您 VM 執行個體的名稱，執行個體的詳細資料頁面會顯示出來。

3. 在「Cloud API 存取權範圍」部分中，按一下「詳細資料」即可查看 API 清單。請找出下列項目：

   1. 如果您看到「This instance has full API access to all Google Cloud Services」(這個執行個體具備所有 Google Cloud 服務的完整 API 存取權)，表示您擁有適當的存取權範圍。
   2. 如果您在「Stackdriver Logging API」(Cloud Logging API 的舊名稱) 旁邊發現您擁有「Write Only」(唯寫) 或「Full」(完整) 權限，表示您擁有適當的執行個體存取權範圍，可以使用 Cloud Logging 代理程式。
   3. 如果您在「Stackdriver Monitoring API」(Cloud Monitoring API 的舊稱) 旁邊看到「Write Only」或「Full」權限，表示您擁有適當的執行個體存取權範圍，可以使用 Cloud Monitoring 代理程式。

修正問題

如果 Compute Engine 執行個體中沒有適當的存取範圍，請在執行個體中新增所需的存取範圍。

下表列出與記錄和監控代理程式相關的範圍：

驗證預設服務帳戶權限

即使您的 Compute Engine VM 執行個體擁有適當的存取權範圍，執行個體的預設服務帳戶也可能無法為代理程式提供正確的身分與存取權管理權限。

如要驗證預設服務帳戶權限，請先找到預設服務帳戶：

1. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面：

   前往「VM instances」(VM 執行個體) 頁面

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

2. 按一下您 VM 執行個體的名稱，執行個體的詳細資料頁面會顯示出來。

3. 在頁面中尋找「Service account」(服務帳戶) 標題。執行個體的預設服務帳戶會列出。該帳戶可能看起來如下：

   [ID]-compute@developer.gserviceaccount.com
   

4. 前往 Google Cloud 控制台的「IAM」頁面：

   前往「身分與存取權管理」頁面

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

5. 選取「按照主體查看」。您會看到人員、群組與服務帳戶的清單。「Role」 欄中是專案中每個主要使用者擁有的角色。

6. 在執行個體預設服務帳戶的列中，應該會看到一或多個角色：

   • 如果您看到「Editor」(編輯者)，表示該角色足以使用所有代理程式。視機構政策設定而定，系統可能會自動將「編輯者」角色授予預設服務帳戶。
   • 如果您看到「Logs Writer」(記錄寫入者)，表示該角色足以使用 Logging 代理程式。針對包含寫入權限的其他 Logging 角色，請參閱 Cloud Logging 的存取權控管。
   • 如果您看到「Monitoring Metric Writer」(監控指標寫入者)，表示該角色足以使用 Monitoring 代理程式。針對包含寫入權限的其他 Monitoring 角色，請參閱 Cloud Monitoring 的存取權控管。

修正問題

如果您的預設服務帳戶沒有適當角色，請嘗試在 [IAM 與管理員] > [IAM] 頁面編輯服務帳戶的角色。新增適當的記錄或監控角色，授權代理程式：Logging > Logs Writer 或 Monitoring > Monitoring Metric Writer。

驗證私密金鑰憑證

在 Compute Engine VM 執行個體上，您可以將代理程式設定為使用擁有正確授權的非預設服務帳戶。在 AWS EC2 VM 執行個體上，您必須將代理程式設定為使用此類服務帳戶。

如要以此方式設定代理程式，您必須為指定的服務帳戶建立私密金鑰憑證，並將這些憑證提供給代理程式。

1. 代理程式會尋找環境變數 GOOGLE_APPLICATION_CREDENTIALS，該變數保留包含私密金鑰憑證的檔案名稱。

2. 如果環境變數不存在，代理程式會在預設位置尋找憑證：

   Linux

   /etc/google/auth/application_default_credentials.json
   

   Windows

   C:\ProgramData\Google\Auth\application_default_credentials.json
   

3. 如果預設位置不含憑證，代理程式會使用中繼資料伺服器中的應用程式預設憑證。

下列資訊可協助您診斷私密金鑰憑證問題：

1. 是否已設定私密金鑰？
2. 私密金鑰對於服務帳戶而言是否仍然有效？
3. 服務帳戶是否擁有代理程式需要的角色？

如要驗證 VM 例項是否安裝有效的私密金鑰憑證，請先確認憑證檔案位於預期位置，然後驗證憑證檔案中的資訊是否有效。

是否存在憑證？

如要查看私密金鑰服務帳戶憑證是否位於您的執行個體上，請在您的執行個體上執行下列 Linux 指令：

sudo cat $GOOGLE_APPLICATION_CREDENTIALS
sudo cat /etc/google/auth/application_default_credentials.json

如果任何指令顯示如下所示的檔案，表示您的執行個體可能擁有有效的私密金鑰憑證。如果兩個指令都顯示一個檔案，則系統會使用由 GOOGLE_APPLICATION_CREDENTIALS 表示的檔案。

{
  "type": "service_account",
  "project_id": "[YOUR-PROJECT-ID]",
  "private_key_id": "[YOUR-PRIVATE-KEY-ID]",
  "private_key": "[YOUR-PRIVATE-KEY]",
  "client_email": "[YOUR-PROJECT-NUMBER]-[YOUR-KEY]@developer.gserviceaccount.com",
  "client_id": "[YOUR-CLIENT-ID]",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "{x509-cert-url}",
  "client_x509_cert_url": "{client-x509-cert-url}"
}

憑證設定不一致，可能會導致服務代理使用與服務要求不同的憑證。舉例來說，如果您在登入殼層的 GOOGLE_APPLICATION_CREDENTIALS 中設定自訂憑證位置，但未在代理程式服務設定中設定該變數，服務就會在預設位置中尋找，而不是在自訂位置中尋找。

如要查看或變更憑證環境變數，請在 /etc/default/google-fluentd 中存取或設定 GOOGLE_APPLICATION_CREDENTIALS。

如果不存在任何憑證檔案，請參閱新增憑證一文。

憑證是否有效？

在憑證檔案中，project_id 是您的 Google Cloud 專案，client_email 會標示專案中的服務帳戶，而 private_key_id 則會標示服務帳戶中的私密金鑰。請將這個資訊與Google Cloud 控制台的「IAM & Admin」(IAM 與管理) >「Service accounts」(服務帳戶) 部分顯示的內容進行比對。

如果符合以下任一條件，則憑證檔案「無」效：

• 您正在查看 Compute Engine 執行個體，但憑證檔案中的 Google Cloud 專案並非包含您執行個體的專案。
• 您正在查看 Amazon EC2 執行個體，但憑證檔案中的 Google Cloud 專案並非您要傳送記錄的 Google Cloud 專案。
• 所列服務帳戶不存在。該帳戶可能已遭刪除。
• 所列服務帳戶未啟用正確角色：Cloud Logging 代理程式適用的「Logs Writer」(記錄寫入者)，以及 Cloud Monitoring 代理程式適用的「Monitoring Metric Writer」(監控指標寫入者)。
• 私密金鑰不存在。該金鑰可能已遭撤銷。

您可以使用 Google Cloud 控制台的「IAM & Admin」(IAM 與管理員) >「Service accounts」(服務帳戶) 部分撤銷憑證。如果沒有有效的憑證，請參閱新增憑證一文，取代現有的憑證或新增憑證。

如果服務帳戶正確，但私密金鑰已撤銷，則您可以建立新的私密金鑰，並將其複製到執行個體。請參閱「建立服務帳戶金鑰」。

否則，您必須如新增憑證部分所述，建立新的服務帳戶。

驗證「排除記錄」查詢

查看目前的排除查詢，確保系統不會意外排除您要查看的記錄。

確認防火牆

如要查看執行個體是否有權存取 logging.googleapis.com，請在執行個體上執行下列 Linux 指令：

curl -sSL 'https://logging.googleapis.com/$discovery/rest?version=v2' | head

如果防火牆封鎖了傳出流量，指令可能需要一些時間才能完成。表示防火牆問題的輸出結果範例：

curl: (7) Failed to connect to 2607:f8b0:4001:c03::5f: Network is unreachable

如要進一步瞭解如何設定輸出流量的規則，請參閱「防火牆規則」。

重新安裝代理程式

安裝最新版本的代理程式可以解決許多問題：

• 如果您確定問題與憑證無關，請直接跳到「在 Linux 和 Windows 上安裝」一節。

• 如要瞭解如何完整安裝代理程式及任何必要憑證，請參閱「安裝記錄代理程式」一文。

其他常見問題

下表列出您可能會在 Cloud Logging 代理程式中遇到的常見問題，並說明如何修正這些問題。

在 Linux 中，Logging 代理程式會將錯誤記錄在 /var/log/google-fluentd/google-fluentd.log 中。在 Windows 中，Logging 代理程式會將錯誤記錄在 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluentd.log 中 (自版本 v1-9 起)。錯誤類別 Google::APIClient::ClientError 表示權限或 API 存取權發生問題。

您可能會在代理程式成功執行之後開始看到錯誤。舉例來說，有人可能已撤銷專案或 VM 執行個體的必要權限。

記錄處理量限制

記錄代理程式可處理的記錄總處理量上限受 CPU 限制。隨著記錄處理量增加，CPU 使用率也可能隨之增加。但在預設設定下，代理程式最多只能使用一個 CPU 核心。因此，當記錄吞吐量突然增加時，代理程式可能會達到 CPU 用量限制。如果這些尖峰值只是暫時性的，Logging 代理程式會緩衝記錄，並在稍後追上進度，最終處理記錄。如果記錄吞吐量持續維持在高水準，記錄可能會溢出緩衝區，並最終遺失。

通常，如果每個記錄項目都是 1000 個位元組的原始文字，且不含任何額外的格式處理作業，記錄代理程式就會達到單一核心 CPU 限制，即每秒約 5,500 個記錄項目。如果記錄項目需要進階處理，例如 JSON 或 Regex 剖析，每秒記錄項目的最高數量可能會較低。

如果需要更高的記錄吞吐量，建議您使用Ops Agent。在 Linux 上，如果記錄項目是 1000 個位元組的原始文字，且不涉及其他處理作業，Ops Agent 每秒可處理約 160,000 個記錄項目。

記錄檔大小超過上限

如果一或多個記錄項目超出大小上限，您可能會在 fluentd 記錄檔中找到類似以下的項目：

Dropping 1 log message(s) error_class="Google::Apis::ClientError" error="Invalid request"

或

Dropping 1 log message(s) error="3:Log entry with size 1000515 bytes exceeds maximum size of 112640 bytes" error_code="3"

如要解決這項錯誤，請裁剪記錄項目，使其不超過最大大小限制。例如，下列程式碼範例會裁剪標記為 mytag 的記錄，資料位於 message 欄位中：

# Cloud Logging only supports log entries that are up to 256 KiB in size.
# Trim the entries to just under that size to avoid dropping them.
<filter [MY_TAG]>
  @type record_transformer
  enable_ruby true
  <record>
    message ${record['message'].length > 256000 ? "[Trimmed]#{record['message'][0..256000]}..." : record['message']}
  </record>
</filter>

記錄重複

LogEntry.insertID 會在代理程式內的處理管道中新增。如果重複記錄中的 insertID 不同，表示記錄檔中的尾端記錄多次重複。這可能發生在記錄檔輪替時，或是 pos 檔案遺失或損毀時。為降低發生此問題的機率，請確認任何 in_tail 輸入內容的位置檔案並未設為位於 /var/log 資料夾或任何可能已啟用記錄輪替功能的其他資料夾。

記錄管道也仰賴 LogEntry.timestamp 欄位來去除重複的記錄。請確認記錄項目的實際時間戳記已正確剖析。如果未設定 Fluentd 從記錄項目剖析原始時間戳記，則 Fluentd 會使用處理記錄項目的時間。因此，如果輸入內容多次讀取，即使記錄列中的時間戳記相同，Fluentd 可能會將這些內容視為具有不同時間戳記的不同記錄項目。

重複的稽核記錄錯誤：Data points cannot be written more than 24h in the past

已知問題會影響 1.8.5 到 1.9.3 版 (含)，當代理程執行超過 24 小時時，會導致下列記錄在資料存取稽核記錄中重複顯示：

Field timeSeries[0].points[0].interval.end_time had an invalid value of "2021-10-20T20:16:34.010866-07:00": Data points cannot be written more than 24h in the past.

解決方法是升級代理程式至 1.9.4 以上版本。

記錄中的 Unicode 字元會被空格或 '�' 取代

根據預設，in_tail 輸入內容會預期輸入檔案為 ASCII 編碼，因此會將任何非 ASCII 字元替換為空格。如要實際擷取 UTF-8 編碼的檔案，您必須在 in_tail 設定中提供兩個選項：

<source>
  @type tail
  …

  encoding UTF-8
  from_encoding UTF-8
</source>

兩者缺一不可。如果只提供 encoding 選項，系統會將擷取記錄中的非 ASCII 字元替換為 '�'。

Google Cloud 主控台回報已移除的代理程式已安裝

卸除代理程式後， Google Cloud 主控台可能需要最多一小時的時間，才能回報這項變更。

Logging 代理程式未顯示在 Windows 的「Uninstall a program」(解除安裝程式) 清單中

如要解除安裝 Logging 代理程式，但該代理程式未列在 Windows 控制台的「Uninstall a program」清單中，請從安裝該代理程式的目錄執行 uninstall.exe。