app-platform-troubleshooting

App Platform トラブルシューティングスキル

推測に頼るデバッグを、迅速な診断と修正に変えます。

基本方針

Traditional: See error → Guess → Change → Push → Wait 5-7 min → Repeat
With skill:  See error → Diagnose → Fix → Verify → Commit proper fix

簡単な選択ガイド

Is the app deployed with running containers?
├── YES → Can we access the shell?
│         ├── YES → LIVE MODE (SDK shell access)
│         └── NO  → LOGS-ONLY MODE (fetch logs)
└── NO (build/deploy failed) → LOGS-ONLY MODE

---

モード 1：ライブトラブルシューティング（クイックスタート）

from do_app_sandbox import Sandbox

app = Sandbox.get_from_id(app_id="<app-id>", component="web")

# Diagnostics
app.exec("env | grep DATABASE")
app.exec("curl -v localhost:8080/health")
app.exec("ps aux | head -10")

完全なガイド：live-troubleshooting.mdを参照してください。

---

モード 2：ログのみ（クイックスタート）

# Runtime logs
doctl apps logs <app_id> <component> --type run

# Build logs
doctl apps logs <app_id> <component> --type build

# Crash logs
doctl apps logs <app_id> --type=run_restarted

完全なガイド：logs-analysis.mdを参照してください。

---

デバッグコンテナ（インフラストラクチャの問題）

約 30～45 秒でデプロイし、インフラストラクチャの問題とアプリケーションの問題を切り分けます。

services:
  - name: debug
    image:
      registry_type: GHCR
      registry: ghcr.io
      repository: bikramkgupta/debug-python
      tag: latest
    http_port: 8080
    envs:
      - key: DATABASE_URL
        value: ${db.DATABASE_URL}

# Run validation suite
validate-infra all
validate-infra database
validate-infra kafka

完全なガイド：debug-container.mdを参照してください。

---

クイックリファレンス：終了コード

コード	シグナル	意味
0	-	正常終了（終了すべきではありません）
1	-	一般的なエラー
127	-	コマンドが見つかりません
137	SIGKILL	OOM による強制終了
143	SIGTERM	正常なシャットダウン

---

クイックリファレンス：よくある修正方法

問題	簡単な修正方法
アプリがすぐに終了する	$PORT でリッスンしているか確認する
502 エラー	ヘルスエンドポイントを確認し、実行中であることを確かめる
データベースへの接続に失敗する	デバッグコンテナを使用し、信頼できるソースを確認する
ビルドに失敗する	依存関係を確認し、ビルドログを確認する
OOM による強制終了	インスタンスのサイズをアップグレードする
ヘルスチェックに失敗する	localhost ではなく、0.0.0.0 にバインドする
起動が遅い	initial_delay_seconds を増やす

---

参考ファイル

• live-troubleshooting.md — SDK のシェルアクセス、診断、ホットフィックス
• logs-analysis.md — ログのパターン、エラーコード、ヘルスチェックの設定
• debug-container.md — インフラストラクチャの検証、検証スイート
• networking-issues.md — DNS、CORS、VPC、ルーティング
• app-maintenance.md — アーカイブ／アーカイブ解除のワークフロー
• diagnostic-scripts.md — スクリプト、テスト戦略、パフォーマンス

---

サポートへのエスカレーションが必要な場合

次のような場合は DigitalOcean サポートにお問い合わせください。

• 再デプロイ後も内部エラーが続く
• リソース制限の引き上げが必要
• 複数のアプリに影響がある（プラットフォームの問題）
• VPC／ネットワークの問題を診断できない

エスカレーションの前に、次の情報を集めてください。

doctl apps get <app_id> -o json > app_info.json
doctl apps logs <app_id> <component> --type run > runtime.log
doctl apps spec get <app_id> > app_spec.yaml

---

他のスキルとの連携

• → deployment：修正後、適切な変更をデプロイする
• → devcontainers：問題をローカルで再現する
• → postgres：データベース固有の設定
• → networking：ネットワークに関する包括的なドキュメント