代理程式疑難排解

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

檢查清單

如果您在安裝或使用 Stackdriver 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」(已透過中繼資料停用),代表您可能正在執行來自 Cloud Marketplace 的映像檔,其中 Stackdriver Logging 代理程式預設為停用。這項功能由 google-logging-enable 執行個體中繼資料鍵 (其值為 0) 所控管。如要重新啟用代理程式,請移除該鍵,或將值設為 1 (請參閱設定執行個體中繼資料)。

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

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

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

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

    • 在 Linux 上,記錄代理程式是一個 fluentd 套件並會將訊息記錄在 /var/log/google-fluentd/google-fluentd.log

      • 如果您看到 HTTP 429 錯誤,表示您可能已經超過了 Stackdriver Logging API 配額。您可以在 GCP 主控台中選取 [APIs & services] (API 和服務) > [Dashboard] (資訊主頁),以查看可用配額。選擇 [Stackdriver Logging API]。

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

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

驗證代理程式安裝

如要查看安裝是否成功,請在記錄檢視器中尋找代理程式的測試記錄項目。

前往記錄檢視器

  1. 在頁面頂端,選擇包含 VM 執行個體的專案:

    • 針對 Compute Engine VM 執行個體,選擇包含 VM 執行個體的專案。
    • 針對 Amazon EC2 VM 執行個體,選擇 Stackdriver 在您將 AWS 帳戶連結至工作區時建立的 AWS LINK 專案。
    • 除非專案包含您的 Compute Engine VM 執行個體,否則請勿選擇工作區專案。
  2. 視窗分頁中,為 VM 執行個體選擇資源:

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

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

如要進一步瞭解記錄檢視器,請參閱查看記錄一文。

測試代理程式

如果您懷疑代理程式無法運作,請查看其是否正在執行,並嘗試向 Stackdriver Logging 傳送一則測試訊息:

Linux 執行個體

下列程序適用於執行 Linux 的 Compute Engine 與 Amazon EC2 VM 執行個體:

  1. 在您的 VM 執行個體上執行下列指令,驗證 Logging 代理程式是否正在執行:

    ps ax | grep fluentd
    

    畫面會顯示類似以下的輸出:

     2284 ?        Sl     0:00 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
     2287 ?        Sl    42:44 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
    
  2. 在您的 VM 執行個體上執行下列指令,傳送測試記錄訊息:

    logger "Some test message"
    

Windows 執行個體

Logging 代理程式有兩個 Windows 服務名稱:

  • StackdriverLogging,適用於版本 v1-5 及之後版本
  • fluentdwinsvc,適用於之前版本

您應該正在執行一項代理程式服務。請使用 PowerShell 在 VM 執行個體上執行下列指令:

  1. 要求提供兩項服務的狀態。如果您知道應執行的服務,可以只使用該服務名稱:

    Get-Service StackdriverLogging,fluentdwinsvc
    
  2. 如果服務未執行,您會看到一則錯誤訊息。如果服務正在執行,您會看到如下所示的輸出:

    Status    Name                DisplayName
    ------    ----                -----------
    Running  StackdriverLogging   Stackdriver Logging
    
  3. 如果您查詢兩項服務,應該會看到一則錯誤訊息和一個 Running 狀態:

    • 如果您沒有看到任何 Running 狀態,表示 Logging 代理程式並未執行。
    • 如果您看到 StackdriverLogging 正在執行,表示您正在執行最新代理程式版本。如要判斷特定版本,請參閱取得版本一文。
    • 如果看到 fluentdwinsvc 正在執行,表示您應該將代理程式升級到最新版本。
  4. 需要管理員權限:如果系統正在執行任意代理程式版本,請執行下列 PowerShell 指令以傳送測試記錄訊息:

    New-EventLog   -LogName Application -Source "Test Source"
    Write-EventLog -LogName Application -Source "Test Source" -EntryType Information -EventID 1 -Message "Testing 123 Testing."
    

尋找測試訊息

傳送測試訊息之後,請在記錄檢視器中尋找該訊息:

前往記錄檢視器

  1. 在頁面頂端,選擇包含 VM 執行個體的專案:

    • 針對 Compute Engine VM 執行個體,選擇包含 VM 執行個體的專案。
    • 針對 Amazon EC2 VM 執行個體,選擇 Stackdriver 在您將 AWS 帳戶連結至工作區時建立的 AWS LINK 專案。
    • 除非專案包含您的 Compute Engine VM 執行個體,否則請勿選擇工作區專案。
  2. 視窗分頁中,為 VM 執行個體選擇資源:

    • 針對 Compute Engine,選擇 [GCE VM Instance] (GCE VM 執行個體)
    • 針對 Amazon EC2,選擇 [AWS EC2 執行個體]
    • 選取 [syslog] (Linux)、[fluent.info] (Windows) 或 [所有記錄]
  3. 您應該會看到包含測試訊息的記錄項目。如果是這樣,則表示 Logging 代理程式已經正常運作。

驗證 Compute Engine 憑證

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

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

驗證存取權範圍

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

  1. 開啟 [Compute Engine] > [VM 執行個體] 頁面:

    開啟執行個體頁面

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

  3. 在頁面中的「Cloud API access scopes」(Cloud API 存取權範圍) 標題下查看。

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

修正問題

如果您在 Compute Engine 執行個體中沒有適當的存取權範圍,請將需要的存取權範圍新增至您的執行個體

下表顯示與 Stackdriver Logging 和 Monitoring 代理程式相關的範圍:

存取權範圍 代理程式權限
https://www.googleapis.com/auth/logging.write 足以使用 Logging 代理程式
https://www.googleapis.com/auth/monitoring.write 足以使用 Monitoring 代理程式

驗證預設服務帳戶權限

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

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

  1. 針對專案開啟 Compute Engine 資訊主頁:

    開啟 Compute Engine 執行個體頁面

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

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

    [ID]-compute@developer.gserviceaccount.com
    
  4. 針對專案開啟「IAM & admin」(IAM 與管理員) >「IAM」 頁面。頁面標題為「Permissions for project [PROJECT_NAME]」([PROJECT_NAME] 專案的權限)

    開啟「IAM」頁面

  5. 選取 [View By: Members] (檢視方式:成員)。您會看到人員、群組與服務帳戶的清單。「Role」(角色) 欄中是專案中每個成員擁有的角色。

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

    • 如果您看到「Editor」(編輯者),表示該角色足以使用所有代理程式。 「Editor」(編輯者) 是指派給 Compute Engine 服務帳戶的預設角色。
    • 如果您看到「Logs Writer」(記錄寫入者),表示該角色足以使用 Logging 代理程式。針對包含寫入權限的其他 Logging 角色,請參閱 Stackdriver Logging 的存取權控管一文。
    • 如果您看到「Monitoring Metric Writer」(監控指標寫入者),表示該角色足以使用 Monitoring 代理程式。針對包含寫入權限的其他 Monitoring 角色,請參閱 Stackdriver Monitoring 的存取權控管一文。

修正問題

如果您的預設服務帳戶沒有適當角色,請嘗試在 [IAM 與管理員] > [IAM] 頁面編輯服務帳戶的角色。新增正確的 Logging 或 Monitoring 角色以授權代理程式:[Logging] > [記錄寫入者] 或 [Monitoring] > [監控指標寫入者]

驗證私密金鑰憑證

在 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

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

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

如要驗證是否已在您的 VM 執行個體上安裝有效的私密金鑰憑證,請先驗證憑證檔案是否存在於其預期位置,然後驗證憑證檔案中的資訊是否有效。之前有效的憑證可使用 GCP 主控台的 [IAM 與管理員] > [服務帳戶] 部分撤銷。如果不存在有效的憑證,請參閱新增憑證一文,取代現有憑證或新增憑證。

是否存在憑證?

如要查看私密金鑰服務帳戶憑證是否位於您的執行個體上,請在您的執行個體上執行下列 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}"
}

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

憑證是否有效?

在憑證檔案中,project_id 是您的 GCP 專案,client_email 可識別專案中的服務帳戶,而 private_key_id 可識別服務帳戶中的私密金鑰。請將這個資訊與 GCP 主控台中 [IAM 與管理員] > [服務帳戶] 部分顯示的內容進行比對。

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

  • 您正在查看 Compute Engine 執行個體,但憑證檔案中的 GCP 專案並非包含您執行個體的專案。
  • 您正在查看 Amazon EC2 執行個體,但憑證檔案中的 GCP 專案並非 AWS 帳戶的連接器專案 (名稱為 AWS Link...)。
  • 所列服務帳戶不存在。該帳戶可能已遭刪除。
  • 所列服務帳戶未啟用正確角色:Stackdriver Logging 代理程式適用的「Logs Writer」(記錄寫入者),以及 Stackdriver Monitoring 代理程式適用的「Monitoring Metric Writer」(監控指標寫入者)
  • 私密金鑰不存在。該金鑰可能已遭撤銷。

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

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

重新安裝代理程式

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

其他常見問題

下表列出您可能會遇到的一些 Stackdriver 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 執行個體撤銷必要權限。

錯誤 原因 解決方案
Windows 上代理程式的安裝程式無法執行 您可能將安裝程式下載至系統目錄。 請將安裝程式移至非系統目錄,例如 C:\Users\[USERID]\
專案尚未啟用 API 您尚未在專案中啟用 Stackdriver Logging API。 請前往 API 主控台,並將 Stackdriver Logging API 的狀態變更為「ON」(啟用)
要求的憑證無效

無法擷取存取憑證 (未設定任何範圍?)
您的 VM 執行個體沒有適當的憑證。如果您使用 Amazon EC2,必須先在 VM 執行個體上安裝憑證才能安裝代理程式。 請參閱授權代理程式一文以安裝憑證。
授權失敗 Logging 代理程式適用的私密金鑰授權未正確設定。 請參閱驗證私密金鑰憑證一文。
呼叫者沒有權限 專案中用於授權的服務帳戶權限不足。該帳戶可能是在 Compute Engine 或 App Engine 內使用的預設服務帳戶,或者可能是用於私密金鑰授權的使用者定義的服務帳戶。帳戶必須擁有可以編輯權限。 在專案的「IAM」頁面中變更服務帳戶的權限。如有必要,您可以按照變更執行個體的服務帳戶與存取權範圍程序,修改現有 VM 的存取權範圍。
無法取得專案 ID Stackdriver Logging 代理程式無法從服務帳戶的私密金鑰憑證檔案取得專案 ID。 如要新增或覆寫代理程式的專案 ID,請在您的 VM 執行個體上,編輯代理程式的設定檔 /etc/google-fluentd/google-fluentd.conf。在 <match **> 部分,新增以下這一行:
project_id [YOUR_PROJECT_ID]
否則,請參閱授權代理程式一文,修正或取代憑證。
Logging 代理程式在發生 logrotate 時停止擷取記錄 在使用 copytruncate 設定來設定 logrotate 時,Logging 代理程式可能會導致您不記得其在輸入檔案中的位置。 建議您使用 nocopytruncate 設定,以確保 logrotate 會移動檔案,而不是截斷檔案。如果您想保留 copytruncate 設定,解決方法是定期重新啟動代理程式。您也可以使用 postrotate 設定重新啟動代理程式。
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁