troubleshooting-astro-deployments

Astro デプロイのトラブルシューティング

このスキルでは、Astro CLI を使用して本番環境の Astronomer デプロイを診断し、トラブルシューティングを行います。

デプロイ管理については、managing-astro-deployments スキルを参照してください。 ローカル開発については、managing-astro-local-env スキルを参照してください。

---

クイックヘルスチェック

概要を確認するには、次のコマンドを実行します。

# 1. List deployments to find target
astro deployment list

# 2. Get deployment overview
astro deployment inspect <DEPLOYMENT_ID>

# 3. Check for errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50

---

デプロイログの表示

-c を使用してログ件数を指定します（デフォルト：500）。ログフラグは組み合わせて使用できません。コマンドごとにコンポーネントまたはレベルのフラグを1つ使用してください。

コンポーネント別ログ

特定の Airflow コンポーネントのログを表示します。

# Scheduler logs (DAG processing, task scheduling)
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50

# Worker logs (task execution)
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

# Webserver logs (UI access, health checks)
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

# Triggerer logs (deferrable operators)
astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30

ログレベルのフィルタリング

重要度でフィルタリングします。

# Error logs only (most useful for troubleshooting)
astro deployment logs <DEPLOYMENT_ID> --error -c 30

# Warning logs
astro deployment logs <DEPLOYMENT_ID> --warn -c 50

# Info-level logs
astro deployment logs <DEPLOYMENT_ID> --info -c 50

ログの検索

特定のキーワードを検索します。

# Search for specific error
astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"

# Search for specific DAG
astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

# Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# Find task failures
astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"

---

調査の全ワークフロー

ステップ 1：問題を特定する

# List deployments with status
astro deployment list

# Get deployment details
astro deployment inspect <DEPLOYMENT_ID>

次の点を確認します。

• ステータス：HEALTHY と UNHEALTHY のどちらか
• ランタイムバージョンの互換性
• リソース制限（CPU、メモリ）
• 直近のデプロイ日時

ステップ 2：エラーログを確認する

# Start with errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50

次の点を確認します。

• 繰り返し発生するエラーパターン
• 繰り返し失敗している特定の DAG
• インポートエラーまたは構文エラー
• 接続または認証情報のエラー

ステップ 3：スケジューラーログを確認する

# Check DAG processing
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30

次の点を確認します。

• DAG の解析エラー
• スケジューリングの遅延
• タスクのキューイングに関する問題

ステップ 4：ワーカーログを確認する

# Check task execution
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

次の点を確認します。

• タスクの実行失敗
• リソースの枯渇
• タイムアウトエラー

ステップ 5：設定を検証する

# Check environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>

次の点を確認します。

• 環境変数の欠落または設定ミス
• シークレットの設定（AIRFLOW__SECRETS__BACKEND）
• 接続の設定

---

よくある調査パターン

DAG の繰り返し失敗

上記の調査の全ワークフローに従ってから、特定の DAG に絞り込みます。

astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

リソースの問題

# 1. Check deployment resource allocation
astro deployment inspect <DEPLOYMENT_ID>
# Look for: resource_quota_cpu, resource_quota_memory
# Worker queue: max_worker_count, worker_type

# 2. Check for worker scaling issues
astro deployment logs <DEPLOYMENT_ID> --workers -c 50

# 3. Look for out-of-memory errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"

設定の問題

# 1. Review environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# 2. Check for secrets backend configuration
# Look for: AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS

# 3. Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>

# 4. Check webserver logs for auth issues
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

インポートエラー

# 1. Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# 2. Check scheduler for parse failures
astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50

# 3. Verify dependencies were deployed
astro deployment inspect <DEPLOYMENT_ID>
# Check: current_tag, last deployment timestamp

---

環境変数の管理

変数の一覧表示

# List all variables for deployment
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Find specific variable
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --key AWS_REGION

# Export variables to file
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --save --env .env.backup

変数の作成

# Create regular variable
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_ENDPOINT \
  --value https://api.example.com

# Create secret (masked in UI and logs)
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value secret123 \
  --secret

変数の更新

# Update existing variable
astro deployment variable update --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value newsecret

変数の削除

# Delete variable
astro deployment variable delete --deployment-id <DEPLOYMENT_ID> --key OLD_KEY

注：変数は環境変数として DAG から利用できます。変更しても再デプロイは不要です。

---

deployment inspect の主なメトリクス

トラブルシューティングでは、次のフィールドに注目してください。

• status：HEALTHY と UNHEALTHY のどちらか
• runtime_version：Airflow バージョンの互換性
• scheduler_size/scheduler_count：スケジューラーのキャパシティ
• executor：CELERY、KUBERNETES、または LOCAL
• worker_queues：ワーカーのスケーリング上限と種類
  • min_worker_count、max_worker_count
  • worker_concurrency
  • worker_type（リソースクラス）
• resource_quota_cpu/memory：全体的なリソース制限
• dag_deploy_enabled：DAG のみのデプロイが機能するかどうか
• current_tag：最後にデプロイしたバージョン
• is_high_availability：冗長性が有効かどうか

---

調査のベストプラクティス

1. まず必ずエラーログを確認する - 最も明らかな失敗はここに表示されます
2. エラーログでパターンを確認する - 同じ DAG が繰り返し失敗しているか、時間的なパターンがあるかを確認します
3. コンポーネント別のトラブルシューティング：
   • ワーカーログ → タスク実行の詳細
   • スケジューラーログ → DAG の処理とスケジューリング
   • Web サーバーログ → UI の問題とヘルスチェック
   • トリガーログ → 遅延可能なオペレーターの問題
4. --keyword を使用して対象を絞って検索する - すべてのログを読むより効率的です
5. inspect コマンドはヘルスダッシュボードです - まず確認してください
6. inspect の出力に含まれる環境変数 - 設定の問題が見つかることがあります
7. ログ件数のデフォルトは500です - 必要に応じて -c で調整してください
8. デプロイ時刻の確認も忘れないでください - 直近のデプロイで問題が発生した可能性があります

---

トラブルシューティングのクイックリファレンス

症状	コマンド
デプロイメントに UNHEALTHY と表示される	astro deployment inspect <ID> + --error ログ
DAG が表示されない	インポートエラーについては --error ログを確認し、--scheduler ログを確認します
タスクが失敗する	--workers ログ + --keyword で DAG を検索します
スケジューリングが遅い	--scheduler ログ + inspect でスケジューラーのリソースを確認します
UI が応答しない	--webserver ログ
接続の問題	変数を確認し、ログで接続名を検索します
インポートエラー	--error --keyword "ImportError" + --scheduler ログ
メモリ不足	inspect でリソースを確認 + --workers --keyword "memory"

---

関連スキル

• managing-astro-deployments：デプロイメントの作成、更新、削除、コードのデプロイ
• managing-astro-local-env：ローカルの Airflow 開発環境の管理
• setting-up-astro-project：Astro プロジェクトの初期化と設定