Freigeben über

Azure Automation: Runbook ストリームを制御しテストとトラブルシューティングに活用する

  • Artikel

このポストは、9 月 17 日に投稿された Azure Automation: Controlling Runbook Streams for Testing and Troubleshooting の翻訳です。

Azure Automation による Runbook の作成と実行では、Runbook を作成する際のテストと、Runbook ジョブを実際に運用する際のトラブルシューティングという 2 つの重要な作業があります。いずれの作業でも、Runbook から有益なログ メッセージを入手して、実行時に何が発生しているか把握する必要があります。こうした作業に役立つのが、Azure Automation の Runbook の基盤となる PowerShell ワークフローが提供するさまざまなメッセージ ストリームです。これらを制御することで、有意義なテストとトラブルシューティングを実施することができます。今回の記事では、Runbook のデバッグとトラブルシューティングを支援する Runbook ストリームの制御について、それらの概念とベスト プラクティスを説明します。

Azure Automation のテスト

Azure Automation では、Runbook 作成ページを使用して Runbook を作成します。このページには、PowerShell ワークフロー コードの編集ウィンドウ、テスト出力の表示ウィンドウ、さらに、アクティビティ、Runbook、アセットを挿入するための各種コントロールがあります (「デバッグに使用する Runbook 出力」セクションのスクリーンショットを参照)。Runbook を作成する場合は、機能が期待どおりに動作することをいくつかのキー ポイントに基づいて確認するのが一般的です。Runbook のドラフトのテストは、[Test] ボタンをクリックするだけで開始できます。テスト ジョブが開始されると [OUTPUT PANE] が表示され、Runbook のストリームがこのウィンドウに書き込まれます。Runbook を効率的にデバッグするためには、ストリームに設定する情報と、どのストリームを使用するかが非常に重要です。このため、次のセクションでは、PowerShell ワークフローが提供するさまざまなストリームの制御方法について説明します。

Runbook ストリームの制御

PowerShell ワークフローは、それぞれ目的が異なる 6 種類のストリームへの書き込みをサポートしています。Runbook では以下のコマンドレットを使用して、これらのストリームを書き込むことができます。

  • Write-Output (英語)
    • Runbook による処理の結果として生成される出力オブジェクト
    • 一般的には返されるデータを表し、この Runbook を呼び出した親 Runbook で使用します。
  • Write-Warning (英語)
    • 警告メッセージ
  • Write-Error (英語)
    • エラー メッセージ
    • エラーは例外とは異なります。既定では、エラーによって Runbook の実行が停止されることはありませんが、キャッチできない例外が発生した場合は Runbook が中断されます。
  • Write-Verbose (英語)
    • 一般的なメッセージとデバッグ情報の詳細レコード
  • Write-Progress (英語)
    • 処理レコードは、Runbook の各アクティビティの開始時と終了時にワークフローによって自動生成されます。
  • Write-Debug (英語)
    • PowerShell コンソールでの使用を目的とするため、Azure Automation では使用しないでください。

各ストリームを使用するタイミングを正しく理解することで、Runbook を作成/デバッグする場合と、運用環境で実行されている Runbook ジョブをトラブルシューティングする場合のそれぞれで、ストリームを有効に活用することができます。

Azure Automation では、主に Runbook 作成ページと Runbook ジョブ ページという 2 つの場所で Runbook ストリームを確認します (以下のスクリーンショットを参照)。Runbook 作成ページには、Runbook の作成とテストで実施するデバッグの際にストリームが表示されます。Runbook を発行し運用環境での実行を開始した後で Runbook ジョブのトラブルシューティングを実施する際には、Runbook ジョブ ページでストリームを確認します。

デバッグに使用する Runbook 出力

Runbook の作成で Runbook をテストする場合、既定では Output、Warning、Error の各ストリームだけが [OUTPUT PANE] に書き込まれます。この動作は、以下のスクリーンショットのようになります。

3 つのストリームだけが書き込まれる理由は、ストリームの既定のユーザー設定に関連しています (詳細については、PowerShell のユーザー設定変数に関する記事 (英語) を参照)。以下のスクリーンショットのとおり、Warning と Error の既定のユーザー設定は "Continue" ですが、Verbose のユーザー設定は "SilentlyContinue" となっています。これは、Write-Verbose コマンドレットを使用している場合メッセージが [OUTPUT PANE] に書き込まれないことを意味しています (このコマンドレット呼び出しに –Verbose スイッチが含まれている場合を除く)。

既定のストリーム設定をテスト用に変更する

テストでは、Verbose ストリームの既定のユーザー設定を上書きできます。

  • すべての Verbose メッセージを [OUTPUT PANE] に表示するには、Runbook の先頭に $VerbosePreference="Continue" を設定します。
    • 一部の Verbose メッセージだけを表示するには、特定の Write-Verbose の呼び出し (または Verbose メッセージを含むすべてのコマンドレット) に "-Verbose" スイッチを追加します。

このようなユーザー設定を追加した Runbook とその結果は、以下のスクリーンショットのようになります。

ベストプラクティス : Azure Automation の Runbook の作成でデバッグを実施する際は、Write-Verbose を使用し、デバッグ メッセージに Write-Debug や Write-Output は使用しません。Write-Debug は対話型のコンソールでの使用に限定し、Write-Output は、別のプロセス (その Runbook を子 Runbook としてインラインで実行した Runbook など) に入力される、出力オブジェクトとしての使用に限定するためです。

ベスト プラクティス: テストとトラブルシューティングのジョブ出力に一般的なコメントを表示する場合は Write-Verbose を使用します。ここでも Write-Output は使用しません。

ベストプラクティス : Write-Progress は Runbook では使用しません。(コンソールの進行状況バーへの表示を目的とする) Progress レコードはテストの [OUTPUT PANE] には表示されないため、デバッグには使用できないからです。次のセクションでは、運用環境のジョブのトラブルシューティングでの Progress レコードの利用について説明しますが、この場合に使用するのは、PowerShell ワークフロー エンジンが自動生成する Progress レコードだけです。

運用環境のジョブのログ記録に使用する Runbook 出力

Runbook を作成し、運用環境で使用するために発行したら、Runbook ジョブで発生する問題のトラブルシューティングに必要な情報の量を検討する必要があります。

運用環境のジョブでは、既定で (テスト ジョブと同様に) Output、Warning、Error の各レコードだけがそれぞれのジョブのデータベースに書き込まれます。既定で格納されるこれらのレコードの種類は、定期的な管理作業で必要とされる情報の重要度に応じて決定されています。Runbook で Warning または Error のユーザー設定変数を "SilentlyContinue" に設定して発行した場合、Runbook の構成でこれらのストリームのログ記録を有効にしていても、運用環境で実行される Runbook ではこれらのストリームについて一切メッセージが出力されません。

以下は、あるジョブの [DASHBOARD] ページと [HISTORY] ページのスクリーンショットです。Output、Warning、Error の各レコードが、既定の設定に基づいて表示されています。ストレージ容量を節約するため、Progress レコードと Verbose レコードは既定では保存されません (詳細については、ブログ記事「Azure Automation: Runbook ジョブの監視とトラブルシューティング」を参照)。

既定のストリーム設定を運用環境のトラブルシューティング用に変更する

Verbose レコードと Progress レコードのログ記録に関する既定の設定は、各 Runbook の [CONFIGURE] ページで変更できます。これらの設定を変更してログ記録を有効にすると、以下のスクリーンショットのようになります。

これらの構成設定は、発行済みの Runbook を運用環境で実行している場合にのみ適用され、Runbook の作成/テスト ページにあるドラフト モードの Runbook には適用されない点に注意してください。また、これらの設定は Set-AzureAutomationRunbook (英語) コマンドレットでも変更できます。

ベストプラクティス : 運用環境で実行している Azure Automation の Runbook のトラブルシューティングを目的に、一般的な情報、進行状況に関する情報、デバッグに関する情報をジョブ履歴に表示するには、Write-Verbose を使用します。こうした情報の表示に Write-Debug や Write-Output は使用しません。

Verbose レコードと Progress レコードのログ記録を有効にした場合の結果は、以下のスクリーンショットのようになります。

ジョブの [HISTORY] ページに表示される情報がかなり増えたことがわかります。これらは、運用環境の Runbook に関するトラブルシューティングに欠かせない情報です。

ベスト プラクティス: Verbose ストリームと Progress ストリームの設定は基本的にはオフのままにして、問題のトラブルシューティングを実施する場合にのみオンにします。

Progress レコードの量は特に膨大になるため注意が必要です。既定では、ワークフローのアクティビティごとにワークフロー エンジンによって 2 つの Progress レコードが書き込まれます。1 つはアクティビティ開始時の Progress レコードで、もう 1 つはアクティビティ完了時の Progress レコードです。この情報に基づいて Runbook の進行状況を追跡しトラブルシューティングする場合を除いて、Progress のログ記録は必ずオフにしてください。

ベストプラクティス : Write-Progress は Runbook では使用しません。トラブルシューティングの際に進行状況の追跡が必要な場合は、PowerShell ワークフロー エンジンが自動生成する Progress レコードの豊富な情報を活用できます。

まとめ

今回の記事で、Runbook のログ記録ストリームを簡単に制御してデバッグとトラブルシューティングの効率化に役立てられることがおわかりいただけたと思います。ベスト プラクティスに忠実に従うことで、Runbook のデバッグとトラブルシューティングを快適かつ正確に制御することができます。

Azure Automation をまだご利用でない方は、プレビュー版にサインアップしお試しください。また入門ガイドをご覧ください。