如何解決 SSM Agent 文件工作者逾時錯誤？

2 分的閱讀內容

我想解決 AWS Systems Manager 中的 "document process failed unexpectedly: document worker timed out" 錯誤。

簡短說明

當您使用下列 AWS Systems Manager 功能時，Systems Manager 命令可能會在目標 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體上失敗：

Run Command
Association
Automation
Session Manager

若出現類似下列錯誤訊息範例的內容，表示 Systems Manager 命令失敗：

"document process failed unexpectedly: document worker timed out; check 12345678-abcd-1234-efgh-123456789012 log for crash reason."

注意： 在上述錯誤訊息範例中，預留位置值 12345678-abcd-1234-efgh-123456789012 代表實際的 ssm-document-worker 或 ssm-session-worker ID 編號。

若要解決此錯誤，請對下列問題進行疑難排解：

資源不足問題
記憶體不足錯誤
執行個體的磁碟空間不足
"Too many open files" 錯誤

解決方法

先決條件： 將 SSM Agent 更新至最新版本。

注意： 您可訂閱 GitHub 網站上的 amazon-ssm-agent/RELEASE NOTES，以接收 SSM Agent 更新通知。

若要找出導致錯誤的問題，請檢視您的 SSM Agent 日誌。接著根據找到的問題，在下列各節中完成疑難排解步驟。

解決資源不足問題

當工作階段遇到資源限制 (例如執行個體超出可用記憶體或磁碟空間) 時，與目標執行個體的工作階段可能會損毀。資源限制會使 SSM Agent 無法正確執行。若要解決此問題，請確認您的執行個體是否有足夠的記憶體和磁碟空間，可用於管理在目標執行個體上執行的工作負載。

解決記憶體不足錯誤

如果執行個體上的處理程序使用所有可用記憶體，且程式或作業系統無法配置空間，則執行個體無法載入其他程式。接著，處理程序會停止回應，而作業系統會終止低優先級的處理程序。

若要解決此問題，請參閱 Troubleshoot an unreachable instance (對無法連線的執行個體進行疑難排解)。對於 Linux 的 OOM 問題，請參閱 Out of memory: end process (記憶體不足：結束程序)。

解決執行個體的磁碟空間不足問題

當您嘗試寫入資料或儲存檔案，但執行個體缺乏可用儲存空間時，Linux 執行個體上就會發生磁碟空間不足錯誤。若要解決此問題，請採取下列動作：

識別分區上使用大量磁碟空間的檔案。
刪除不必要的檔案或移動資料，以釋放分區上的空間。
確認工作目錄是否有足夠的空間，包括位於 /var/lib/amazon/ssm 中的 Systems Manager 協同運作資料夾。
增加磁碟區大小。如需相關說明，請參閱如果收到檔案系統上沒有剩餘空間的錯誤，如何增加 EBS 磁碟區的大小？

解決 "too many open files" 錯誤

當 Linux 執行個體停止處理 Systems Manager Run Command，因為 SSM Agent 工作者處理程序失敗時，您會收到 "too many open files" 錯誤。當執行個體開啟過多檔案時，SSM Agent 無法啟動命令處理器，並會在 SSM Agent 日誌中回報此錯誤。此錯誤通常發生於下列情況：

SSM Agent 處理程序達到作業系統使用者帳戶所允許的最大開啟檔案數。
系統中開啟的檔案總數達到系統範圍內的最大開啟檔案限制。
系統已達到核心的 inotify 監控上限，此上限會監視檔案系統變更。

若要解決此問題，請完成下列步驟：

識別 SSM Agent 處理程序的 PID：
```
sudo ps -C amazon-ssm-agent -o pid=
```
注意： 對於下列步驟中的命令，請將 PID 替換為此命令傳回的處理程序 ID。
檢查 SSM Agent 處理程序的檔案描述元極限。第一個數字代表軟性限制 (目前強制執行的限制)，第二個數字代表硬性限制 (軟性限制可以達到的最大值)：
```
sudo cat /proc/PID/limits |grep "Max open files"
```

檢查 SSM Agent 處理程序開啟的檔案總數：

sudo lsof -p PID |wc -l

將開啟的檔案總數 (得自步驟 3) 和硬性限制 (得自步驟 2) 進行比較。如果開啟的檔案總數接近硬性限制，則系統無法開啟新檔案。

若要解決此問題，請在 SSM Agent 服務組態檔案中增加硬性限制值，然後重新啟動 SSM Agent。

增加硬性體限制時，請考慮執行個體的工作負載需求，包括並行使用者數、網路連線和檔案作業。Linux 發行版本會設定預設硬性限制，以防止意外耗盡資源。

若要更新硬性限制，請根據您的作業系統採取下列動作：

針對 Amazon Linux 1、Ubuntu 14.04 以及搭配 .deb 套件的 Ubuntu 16.04，請執行下列命令：

echo "limit nofile example-hard-limit" >> /etc/init/amazon-ssm-agent.override

針對 Amazon Linux 2、RHEL 7.x 與 RHEL 8.x/，請執行下列命令：

sudo systemctl edit amazon-ssm-agent

然後，當編輯器開啟時，將下列程式碼新增至您的檔案中：

[Service]
LimitNOFILE=example-hard-limit

針對 Ubuntu 22.04 LTS、20.10 STR & 20.04 以及 18.04，請執行下列命令：

sudo systemctl edit snap.amazon-ssm-agent.amazon-ssm-agent

然後，當編輯器開啟時，將下列程式碼新增至您的檔案中：

[Service]
LimitNOFILE=example-hard-limit

注意： 在上述命令中，請將 example-hard-limit 替換為您更新的值。

請務必對新的硬性限制進行壓力測試。監控您的新硬性限制，如果新硬性限制造成其他問題，請進行調整。

檢查工作者日誌

若要識別文件工作者逾期錯誤的根本原因，請檢閱 SSM Agent 日誌以及執行個體上的作業系統層級日誌。

請根據您的作業系統，在下列位置檢查與 SSM Agent 相關的錯誤訊息、損毀報告或核心問題的作業系統層級日誌：

Windows：
C:\Windows\System32\winevt\Logs
Ubuntu 和 Debian：
/var/log/syslog
Amazon Linux、CentOS 和 RHEL：
/var/log/messages
Suse：
/var/log/messages

如果需要啟用偵錯記錄以進行更詳盡的疑難排解，請參閱 Allowing SSM Agent debug logging (允許 SSM Agent 偵錯記錄功能)。

注意： SSM Agent 偵錯記錄會產生大量日誌資料，這可能會影響系統儲存空間。最佳實務是在完成疑難排解後，關閉偵錯記錄功能。