View a markdown version of this page

疑難排解 - AWS HealthOmics
對工作流程進行故障診斷對執行指標進行故障診斷對呼叫快取問題進行故障診斷對資料存放區進行故障診斷使用 Kiro CLI 進行故障診斷

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

疑難排解

下列主題可協助您針對使用 HealthOmics 工作流程和資料存放區時遇到的問題進行疑難排解。

對工作流程進行故障診斷

如何對失敗的執行進行故障診斷？

使用 GetRun API 操作來擷取失敗原因。如需詳細資訊，請參閱執行失敗原因。

如何對失敗的任務進行故障診斷？

檢閱任務失敗訊息中的錯誤代碼，以了解失敗。檢閱 CloudWatch 中的任務日誌，以查看任務的詳細記錄訊息。如果您沒有收到詳細的日誌訊息，您可以修改工作流程以輸出其他日誌陳述式。如需詳細資訊，請參閱使用 CloudWatch Logs 監控 HealthOmics。

在哪裡可以找到引擎日誌？

HealthOmics 會針對所有執行，近乎即時地將引擎日誌發佈至 CloudWatch （成功和失敗）。引擎日誌也會在執行完成後交付到您的 Amazon S3 儲存貯體。如需詳細資訊，請參閱使用 CloudWatch Logs 監控 HealthOmics及Amazon S3 中的日誌。

如何減少工作流程的輸入參數大小？

您可以為工作流程指定最多 256 KB 的輸入參數。您可以使用目錄匯入或範例工作表來維持在此大小限制內。如需詳細資訊，請參閱管理執行參數大小。

為什麼我的執行未完成？

如果您的程式碼發生問題，且程序未正確結束，您的執行可能會變得沒有回應或「卡住」。如需如何防止和捕捉無回應執行的詳細資訊，請參閱 無回應執行的指引。

對執行指標進行故障診斷

為什麼我的任務執行速度比預期慢？

如果任務是集中處理單元 (CPU) 繫結、圖形處理單元 (GPU) 繫結或正在等待輸入/輸出 (I/O)，則任務可能會緩慢執行。使用執行的近乎即時 CloudWatch 指標，在任務仍在執行時查看資源使用率：

  • aws.omics.task.cpu.usage 與 比較aws.omics.task.cpu.limit。限制的持續用量表示任務受限於 CPU，而且可能受益於更多配置的 CPU。

  • 對於 GPU 工作負載，請檢查 aws.omics.task.gpu.utilization。低使用率可能表示任務未有效使用 GPU。

  • 檢查 aws.omics.task.filesystem.io和 aws.omics.task.filesystem.operations是否有 I/O 瓶頸。

如需詳細資訊，請參閱執行私有工作流程的指標。

為什麼我的執行因為儲存空間不足而失敗？

當執行耗盡其共用檔案系統的儲存體時，執行可能會失敗。比較 aws.omics.run.filesystem.usage，其會報告執行共用檔案系統上正在使用的儲存體，而 aws.omics.run.filesystem.limit會報告其總容量。您可以建立儀表板或警示來監控儲存使用率。如需詳細資訊，請參閱執行私有工作流程的指標。

如何調整工作流程的運算和儲存體大小？

執行一次工作流程並檢閱 CloudWatch 指標，以比較實際使用率與配置的限制：

  • 如果 CPU、GPU 或記憶體用量遠低於限制，您可以降低配置成本。

  • 如果用量持續達到限制，請增加配置以改善效能或避免失敗。

  • 使用 aws.omics.run.filesystem.usage 為執行設定適當的檔案系統大小。

如需詳細資訊，請參閱執行私有工作流程的指標。

為什麼我看不到執行的指標？

如果執行和任務指標未出現在 CloudWatch cloudwatch.aws/omics的範圍中，請檢查下列項目：

  • 確認用於執行的 IAM 角色具有將指標發佈至 CloudWatch 的許可。

  • 指標會在執行期間近乎即時地發佈。允許第一個資料點出現短暫延遲 （約 30 秒）。

  • 執行時間少於 30 秒的任務可能沒有指標。

  • 確認您檢視的是正確的 AWS 區域和帳戶。

如需詳細資訊，請參閱執行私有工作流程的指標。

這與執行資訊清單日誌資源統計資料有何不同？

執行資訊清單日誌會報告已完成執行的彙總統計資料，例如最大和平均 CPU 和記憶體，因此您可以檢閱已完成執行的最佳化機會。CloudWatch 執行指標是時間序列：HealthOmics 依 中列出的頻率發佈資料點可用的指標，因此您可以在執行進行時監控使用率變更，並使用更精細的資料對執行進行故障診斷。如需執行指標的詳細資訊，請參閱 執行私有工作流程的指標。

Query Studio 中的執行指標與 Nextflow 執行報告有何不同？

這兩個報告工作流程的資源使用率。它們在時間、引擎涵蓋範圍以及使用方式方面有所不同。使用執行指標來監控進行中的執行，並使用 Nextflow 執行報告來檢閱已完成的執行。

  • 執行指標可在執行時近乎即時地提供，因此您可以監控進度、設定警示，以及對仍在進行的執行進行疑難排解。Nextflow 執行報告會在執行完成時寫入，因此您只能在事實之後使用它來檢閱執行。

  • HealthOmics 會針對每個私有工作流程執行發出執行指標，無論執行使用哪個工作流程引擎。執行報告專屬於 Nextflow，且 HealthOmics 只會在您將其設定為在 下寫入時匯出它/mnt/workflow/output/。

  • 執行指標是 CloudWatch 時間序列，因此您可以使用 PromQL 來查詢它們、對其發出警示，並將它們新增至儀表板。執行報告是執行 Amazon S3 輸出位置中的靜態檔案。

如需執行報告的詳細資訊，請參閱 產生 Nextflow 執行報告。如需執行指標的詳細資訊，請參閱 執行私有工作流程的指標。

對呼叫快取問題進行故障診斷

下列主題可協助您針對呼叫快取時遇到的問題進行疑難排解。

為什麼我的執行不會儲存至快取？

  1. 透過檢查 GetRun API 操作回應中的 cacheId 欄位，確認執行已設定為使用快取。使用 CLI，執行此命令：aws omics get-run —id <run_id>。

  2. 如果執行成功，請確認 GetRun 回應中傳回的快取行為為 CACHE_ALWAYS。如果快取行為設定為 CACHE_ON_FAILURE，則執行只會在失敗時儲存至快取。

為什麼任務不使用快取項目？

在 /aws/omics/WorkflowLog CloudWatch 日誌群組中，開啟執行快取的日誌串流：runCache/<cache_id>/<cache_uuid>。

  1. 確認先前的執行已為您預期要快取的任務建立快取項目。儲存到快取的執行會以 CACHE_ENTRY_CREATED 的日誌訊息記錄。

  2. 找到任務的 CACHE_MISS 日誌，並執行已完成的日誌。如果沒有日誌項目，請檢查執行是否已設定為使用快取。

  3. 如果已建立快取項目，請確認兩個任務CPUs、記憶體、GPUs 和容器摘要都相同。建立快取項目之任務的任務 ARN 位於日誌訊息中。

  4. 如果兩個任務的運算需求相符，請確認任務之間的輸入未變更。若要這樣做，請開啟引擎日誌。引擎日誌可在 CloudWatch Log Group /aws/omics/WorkflowLog 中用於所有執行。完成之後，也可以在執行的輸出目錄中使用它們。

為什麼停用任務的呼叫快取？

檢查任務是否設定為使用工作流程引擎功能選擇退出快取：

  • 對於 WDL 工作流程：檢查中繼區段true中的任務是否將揮發性設定為

  • 對於 Nextflow 工作流程：檢查任務是否將快取指令設定為 false

  • 對於 CWL 工作流程：檢查任務是否已針對 WorkReuse 功能將 enableReuseWorkReuse false 設定為

對資料存放區進行故障診斷

為什麼我的讀取集上的 S3 GetObject 失敗？

最常見的是，失敗是因為缺少許可。序列存放區 S3 讀取許可是一種雙向組態，需要序列存放區 S3 存取政策允許存取，且 IAM 主體必須連接允許存取的政策。如需政策需求的詳細資訊，請參閱 使用 Amazon S3 URIs 存取資料的許可。檢查下列組態是否已就緒：

  • 序列存放區 S3 存取政策明確允許存取 IAM 主體或主體帳戶的根目錄。

  • 檢查 IAM 主體是否具有明確提供存取資源許可的政策。請注意，定義許可時，IAM 主體政策必須使用存取點 ARN，而不是存取點別名型路徑，而且 ARN 處於條件中，而不是用來指定資源。

  • 如果您的存放區使用客戶受管金鑰 (CMK-KMS)，請確保 IAM 主體對金鑰具有 kms:decrypt 許可。如需跨帳戶設定用量，請參閱 KMS 跨帳戶存取指南。

如果您有使用標籤型存取控制的政策，請確定下列事項：

  • 確保序列存放區已完成標籤同步。因此，存放區的狀態必須為 active，而不是 updating。

  • 確保讀取集和政策的標籤索引鍵或索引鍵值中沒有錯別字。

為什麼我在 Athena 中看不到註釋存放區或變體存放區？

在 Lake Formation 中，請務必根據與您共用的存放區建立資源連結。建立您有權存取的資源連結後，應該會在 Athena 中顯示該存放區。如需詳細資訊，請參閱設定 Lake Formation 以使用 HealthOmics。

為什麼我無法存取 Athena 中的資料存放區？

如果您的註釋或變體存放區可見，但您收到錯誤訊息，指出存取遭拒，請檢查您正在使用的查詢引擎版本。僅支援使用引擎版本 3 執行的查詢。若要進一步了解 Athena 查詢引擎版本，請參閱 Amazon Athena 文件。

使用 Kiro CLI 進行故障診斷

Kiro CLI 可以透過下列方式協助您簡化故障診斷程序：

  • 分析工作流程執行和偵錯任務失敗

  • 收集相關日誌和錯誤訊息

  • 建立連接所有必要偵錯日誌的 AWS 支援案例

  • 從提交至 AWS Support 的資訊中修訂個人身分識別資訊 (PII)

如需搭配 使用 Kiro CLI AWS HealthOmics 進行疑難排解和建立支援案例的詳細資訊，請參閱 GitHub 上的 HealthOmics Agentic 生成式 AI 教學課程。

警告

使用 Kiro CLI 時，請先檢閱所有產生的內容和建議的動作，再繼續。提供意見回饋以改善回應品質，並符合您工作流程的需求。如需詳細資訊，請參閱 Kiro 的安全考量和最佳實務。