DeployAngel

Python 向け DeployAngel

Django、FastAPI、Starlette、Flask、および Celery と RQ のジョブに対応する DeployAngel エージェントです。本番環境でアプリがどのように動作しているかを監視し、プロセスごとに毎分、小さく集約したペイロードを 1 つ報告します。DeployAngel はその情報を使ってデプロイごとに検証を行い、リリースが承認済みとなり、監視を終了できるタイミングを、あなた（またはコーディングエージェント）に知らせます。

インストール

Python 3.10 以降が必要です。このパッケージ自体には依存関係はありません。

pip install deployangel

本番環境のすべてのプロセス（ウェブサーバーとジョブワーカーの両方）で、以下を設定してください。

DEPLOYANGEL_TOKEN=da_live_...           # an ingestion token with the telemetry scope

Heroku では、DeployAngel アドオンが自動的に設定します。

Django

Django 4.2 以降に対応しています。

# settings.py
INSTALLED_APPS = [
    # ...
    "deployangel.django",
]

これだけです。このアプリは DeployAngel のミドルウェアを MIDDLEWARE の先頭に配置し（配置場所を指定する場合は、ご自身でリストに追加してください）、WSGI と ASGI の下でリクエストを記録し、Celery がインストールされていれば計測を行います。DEBUG がオフの場合、レポートが有効になります。

FastAPI と Starlette

FastAPI 0.100 および Starlette 0.27 以降に対応しています。

import deployangel.fastapi

app = FastAPI()
deployangel.fastapi.init(app)      # deployangel.starlette.init(app) for Starlette

リクエストの処理を開始する前に、アプリの作成時に呼び出してください。

Flask

Flask 2.3 以降に対応しています。

import deployangel.flask

app = Flask(__name__)
deployangel.flask.init_app(app)

Celery

Celery 5.3 以降に対応しています。Django では自動的に設定されます。それ以外の場合は、ワーカープロセスでエージェントを起動できるよう、Celery アプリの作成時に init を呼び出してください。

import deployangel.celery

app = Celery("shop")
deployangel.celery.init(app)

RQ

RQ 1.16 以降に対応しています。DeployAngel のワーカークラスを使ってワーカーを実行してください。

rq worker -w deployangel.rq.Worker               # or deployangel.rq.SimpleWorker
python manage.py rqworker --worker-class deployangel.rq.Worker   # django-rq

RQ は各ジョブをフォークしたプロセスで実行し、ジョブの終了直後にそのプロセスを終了します。そのため、ワーカーは RQ が Redis に保存した情報を使い、ジョブの完了後に記録します。失敗したジョブのトレースバックは含まれますが、RQ が再試行する試行の例外は含まれません。

実行中のリリース

エージェントは、実行中のリリースを把握する必要があります。次の順序で情報を取得します。

1. DEPLOYANGEL_REVISION（コミット SHA）と、設定されている場合は DEPLOYANGEL_RELEASE_VERSION
2. Heroku の dyno メタデータ。有効にするには heroku labs:enable runtime-dyno-metadata と heroku labs:enable runtime-dyno-build-metadata を実行してください。どちらも次回のデプロイから反映されます
3. Kamal：KAMAL_VERSION
4. Render：RENDER_GIT_COMMIT
5. Fly.io：FLY_IMAGE_REF から取得するデプロイのイメージタグ。Fly.io はコミットを設定しないため、 コミット単位の変更追跡にはコミットを渡してください（Dockerfile に ENV DEPLOYANGEL_REVISION=$GIT_SHA を設定し、--build-arg GIT_SHA=$(git rev-parse HEAD) を指定します）
6. Railway：RAILWAY_GIT_COMMIT_SHA または RAILWAY_DEPLOYMENT_ID
7. Coolify：SOURCE_COMMIT。Dokku：GIT_REV
8. アプリのルートにある REVISION ファイル
9. Git チェックアウト：.git から、またはアプリのルートより最大 3 階層上までさかのぼって、git を実行せずに取得するコミット HEAD。git pull、Fabric、Ansible でデプロイされたサーバーが対象です
10. Fargate を含む ECS：ECS が提供するメタデータエンドポイントから取得するコンテナのイメージ（起動時にローカルリクエストを 1 回実行します）
11. コードフィンガープリント：コミットがない場合、エージェントがすでに送信するファイルダイジェスト（後述）のハッシュの先頭 12 文字に code: を付けたもの。同じコードなら同じフィンガープリントになるため、変更のないコードを再デプロイしても新しいリリースにはなりません。これは起動時ではなく、レポーターの開始時にバックグラウンドで計算されます。ファイルダイジェストを有効にする必要があります。コミットがなくても、DeployAngel はリリースで変更されたファイルを表示しますが、コミットやプルリクエストは表示されません。そのため、エージェントは警告をログに記録します。可能であれば DEPLOYANGEL_REVISION を設定してください

その他の Docker デプロイでは、コミットをイメージに埋め込んでください。 deployangel install docker は Dockerfile の末尾に ARG GIT_SHA と ENV DEPLOYANGEL_REVISION=$GIT_SHA を追加します。これによりキャッシュ済みレイヤーは無効化されません。ビルド時には --build-arg GIT_SHA=$(git rev-parse HEAD) を指定してください。DigitalOcean App Platform では、アプリの仕様に DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH} を設定してください。

送信する内容

• HTTP リクエスト数、ステータスコード別の 4xx／5xx 件数、未処理の例外、およびレイテンシのヒストグラムを、アプリごととルートごとに送信します。
• ルートは、生のパスではなく、フレームワークが照合したパターン（GET /users/<int:pk>/、GET /items/{item_id}）として記録されます。ペイロードごとに送信されるルートは最大 100 個で、残りは __other__ にまとめられます。
• バックグラウンドジョブ：タスクごとに、実行回数、失敗回数、破棄されたジョブ、所要時間、キューのレイテンシを送信します。キューのレイテンシを計測するため、Celery のタスクメッセージには、送信時刻を示す追加ヘッダー deployangel_published_at が 1 つ付与されます。
• 各分の終了時点で実行中のタスクと、それぞれで最も長く実行されているタスクの経過時間を送信するため、停止したタスクを検知できます。
• リリースの識別情報、ランタイムのバージョン、プロセスごとのインスタンス ID。
• 例外：安定したフィンガープリント、例外クラス、メッセージの最初の行、およびアプリケーションのフレームのみ（ファイルパスと関数名）。メッセージ内の数字、ID、メールアドレス、UUID、長い 16 進文字列、引用符で囲まれた値、およびリクエストのホスト名はプレースホルダーに置き換えられます。それ以外の単語はそのまま保持されます。たとえば、Payment failed for Jane Doe はそのまま送信されます。アプリのメッセージに個人情報や健康情報が含まれる可能性がある場合は、メッセージを無効にしてください。
• プロセスごとに 1 回：ルートテーブル（各ビューのモジュールとファイルを含む）、タスク名とファイル、Celery Beat の設定または django-celery-beat のテーブルで宣言された定期スケジュール、クリティカルフロー、およびファイルダイジェスト（相対パスとハッシュ。ファイルの内容は含みません）。これにより、DeployAngel はリリースで変更されたルートを把握できます。ダイジェストは DEPLOYANGEL_FILE_DIGESTS=false で無効にできます。

リクエスト本文、パラメーター、ヘッダー、Cookie、SQL、ログ、ユーザーデータは送信されません。

データと料金

• すべてのデータは、米国の DigitalOcean 上で稼働する DeployAngel のホステッドサービスに送信されます。セルフホスト可能なバージョンはなく、リージョンも選択できません。
• テレメトリは 21 日間保持され、リリース履歴はプランに応じて 7 日、30 日、または 90 日間保持されます。プライバシーポリシーに、詳細と DeployAngel が利用するサービスが記載されています。
• ベータ期間中、DeployAngel は無料で利用できます。有料プランの開始前には通知があります。料金をご覧ください。

安全性

• リクエストやジョブの処理中に、ネットワーク通信は発生しません。記録時に更新されるのはメモリー内のカウンターだけです。
• ペイロードはバックグラウンドスレッドから、短いタイムアウトを設定して 1 分に 1 回送信されます。
• DeployAngel に接続できない場合、バッファーのサイズは制限され（gzip 圧縮された JSON を 10 件保持）、古いものから破棄されます。アプリがブロックされたり、失敗したりすることはありません。
• フォーク環境（Gunicorn、Celery の prefork プール、uWSGI）でも安全に動作し、シャットダウン時には処理中の分のデータがフラッシュされます。uWSGI では、スレッドを有効にしてください（enable-threads = true）。

python bench/overhead.py で計測できます。Python 3.14 を搭載した Apple M シリーズのノート PC では、リクエストの記録に約 1.7 µs が追加されます。すべてのルート、ジョブ、チェックポイント、例外のリストが上限に達している場合でも、未送信の 10 分分を含め、エージェントが使用するメモリーは約 0.5 MB です。

設定

ほとんどのアプリでは、環境変数だけで十分です。Django では設定を DEPLOYANGEL 辞書に記述します。それ以外では、init の前に deployangel.configure を呼び出します：

# settings.py
DEPLOYANGEL = {
    "environments": ["production", "staging"],   # default: production only
}

# or anywhere else
deployangel.configure(environments=["production", "staging"])

エージェントは、一覧にある環境で報告します。Python フレームワークには環境名がないため、DEPLOYANGEL_ENVIRONMENT が設定されていればその値を使用し、そうでなければフレームワークのデバッグモードがオンの場合は development、オフの場合は production を使用します。DEPLOYANGEL_ENABLED=true|false を設定すると、どの環境でも報告を強制的に有効または無効にできます。DEPLOYANGEL_URL は API エンドポイントを上書きします（デフォルトは https://api.deployangel.com）。

ファイルパスはアプリのルートからの相対パスです。デフォルトでは作業ディレクトリです（Heroku やほとんどのコンテナでは、リポジトリのルートです）。プロセスが別の場所から起動する場合は、 DEPLOYANGEL_ROOT を設定してください。

サインアップやパスワードのリセットなどの重要なフローは、クリアランスレポートに常に表示されます：

DEPLOYANGEL = {
    "critical_flows": {"password_reset": ["POST /password-reset/", "job:accounts.tasks.send_reset_email"]},
}

ヘルスチェックは記録されません。ロードバランサーや稼働状況モニターはヘルスチェックを頻繁に呼び出し、常に高速で応答するため、記録すると、実際のページよりもアプリが活発で健全であるように見えてしまいます。エージェントは、django-health-check、django-alive、django-watchman がマウントされている場所を問わず認識します。また、一般的なパス（/up、/health、/healthz、/healthcheck、/health_check、/livez、/readyz、/statusz、/ping、/ht、/alive）にあるすべてのルートも認識します。別の場所にある場合は、ダッシュボードに表示されるとおりに指定してください。ヘルスチェックへの HEAD リクエストも除外されます：

DEPLOYANGEL = {"ignored_routes": ["GET /status/"]}

例外メッセージ

例外のメッセージを含めず、クラス、フィンガープリント、アプリケーションのフレームのみを送信するには：

DEPLOYANGEL = {"exception_messages": False}   # or DEPLOYANGEL_EXCEPTION_MESSAGES=false

メッセージがフィンガープリントに使われないため、グループ化、新しい例外の検出、判定は同じように機能します。ただし、ダッシュボード、通知、AI による調査でメッセージのテキストが表示されなくなります。

処理済みの例外

コードで捕捉された例外は検知されません。コンテキストとして報告するには（処理済みの例外によってリリースが失敗することはありません）：

try:
    sync_inventory()
except UpstreamError as error:
    deployangel.notify(error)

定期実行ジョブ

DeployAngel では、宣言された定期タスクがスケジュールどおりに実行されることを想定しています。Celery Beat の beat_schedule（Beat の起動時から繰り返す crontab とインターバル）を、Celery が使用するタイムゾーンで読み込みます。また、django_celery_beat がインストールされている場合は、有効な定期タスクも読み込みます。ソーラースケジュールは読み込まれません。また、ジョブが Redis 内にしか存在しない RQ のスケジューラーも読み込みません。DeployAngel は、ジョブの実行履歴からも定期ジョブを学習します。

Cron、Heroku Scheduler、django-crontab

cron、Heroku Scheduler、Kubernetes CronJob など、アプリの外部からスケジュールに従って開始される処理は、Celery Beat からは認識できません。サーバーのタイムゾーンを使う場合は、実行時の名前と cron の行、または "every day at 4am" のような表現で宣言してください。別のタイムゾーンを指定することもできます（"0 3 * * * America/New_York"）：

DEPLOYANGEL = {
    "recurring_jobs": {
        "shop.tasks.send_receipts": "0 3 * * *",            # a Celery or RQ task
        "manage.py send_invoices": "every day at 4am",      # python manage.py send_invoices
        "nightly import": "30 2 * * *",                     # deployangel.task("nightly import")
    },
}

• タスクは、実行される場所を問わず記録されます。

• Django の管理コマンドは、"manage.py <command>" という名前であれば、コードを変更せずに記録されます。

• その他のコードは、ラップすると記録されます。例外は記録されたうえで再送出されます：

  with deployangel.task("nightly import"):
      run_import()
  
  @deployangel.task("nightly import")
  def run_import(): ...
  

django-crontab の CRONJOBS 設定は、django_crontab がインストールされている場合に自動的に読み込まれます。各ジョブはサーバーのタイムゾーンでスケジュールどおりに実行されるものとして扱われ、ジョブを変更せずに実行が記録されます（call_command を呼び出すジョブは manage.py <command> として記録されます）。

チェックポイント

エラーやレイテンシだけでは、気づかれないまま実行されなくなった処理は検出できません。重要なビジネスイベントを、次の1行でカウントします。

deployangel.checkpoint("order.created")
deployangel.checkpoint("webhook.stripe.processed", count=len(events))

DeployAngel は、各チェックポイントの通常の発生率をトラフィックに照らして学習し、その発生率が急激に低下したり、止まったりしたリリースを失敗と判定します。すべてのリクエストやジョブが成功していても検出されます。フラグが立つのは低下のみで、トラフィックが不十分なチェックポイントによってリリースが承認されなくなることはありません。チェックポイントはクリティカルフロー（checkpoint:order.created）の一部にすることもできます。

エージェントは、各チェックポイントが HTTP リクエストの処理中に発生したか、ジョブの実行中に発生したか（Celery タスクまたは RQ ジョブ。リクエスト内で即時実行されたものも含む）も記録します。これにより、DeployAngel は適切なトラフィックと照合できます。リクエスト内で記録されたチェックポイントにはリクエストを、ジョブ内で記録されたものにはジョブの実行回数を使用します。

どこから呼び出しても安全です。例外を発生させず、ネットワークにもアクセスせず、レポート対象環境以外では無視されます。名前には英字、数字、. _ : - を使用でき（最大100文字）、IDを含めず、固定の名前だけを使用してください。1分あたりにカウントされる名前は100種類までです。

デプロイの登録

DeployAngel は、エージェントがリリースを初めて報告した時点で新しいリリースを検知し、そこから検証を開始します。設定は不要です。Heroku では、アドオンがすべてのリリースを自動的に登録します。

CI からデプロイを登録するには、ダッシュボードで CI デプロイ用に作成した API トークンを使用します。これにより、起動しないリリースも検出できます。GitHub Actions では、デプロイのステップの後にDeployAngel/verify-releaseを追加します。デプロイを登録して判定を待ち、リリースが失敗した場合はステップを失敗させます。

- uses: DeployAngel/verify-release@v1
  with:
    api-token: ${{ secrets.DEPLOYANGEL_API_TOKEN }}

それ以外の場所では、コミットを送信します。

curl -fsS https://api.deployangel.com/api/v1/deployments \
  -H "Authorization: Bearer $DEPLOYANGEL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"commit\": \"$GIT_SHA\"}"

コマンドラインとコーディングエージェント

パッケージには deployangel コマンド（python -m deployangel でも実行可能）と、コーディングエージェント向けの MCP サーバーが含まれています。どちらも DeployAngel の API だけと通信します。エージェントを起動したり、アプリを読み込んだりすることはないため、パッケージがインストールされている場所ならどこでも実行できます。また、何もインストールせずに uvx deployangel で実行することもできます。DEPLOYANGEL_API_TOKEN にトークンを設定してください。「CLI & coding agents」トークンでは判定を読み取ることができ、「CI deploys」トークンではデプロイの登録とチェックの報告もできます。

コーディングエージェントに DeployAngel のセットアップを任せるには、DeployAngel のアプリページで「Set up with your coding agent」を使用します。トークンではなく、一度だけ使えるセットアップコードが発行されます。deployangel setup --code=CODE でコードを引き換えると、アプリのトークンと「CI deploys」トークンが .deployangel/credentials.json に保存されます。このファイルは自分だけが読み取れる状態に保たれ、Git の対象から除外されます。どちらのトークンも表示されません。DEPLOYANGEL_API_TOKEN が設定されていない場合、コマンドと MCP サーバーは保存されたトークンを使用します。deployangel token app（または api）を使うと、ホストや CI のシークレットにパイプするための保存済みトークンが出力されるため、画面やエージェントとの会話に表示されることはありません。

fly secrets set DEPLOYANGEL_TOKEN=$(deployangel token app)
deployangel token api | gh secret set DEPLOYANGEL_API_TOKEN

deployangel verify --wait                   # current git HEAD, until a verdict
deployangel verify --wait --until=initial   # return at the 15-minute initial check
deployangel status                          # latest deployment
deployangel plan                            # what to exercise so a release clears sooner
deployangel exercise --url=https://example.com  # send the plan's read-only requests to production
deployangel release --commit=$SHA           # register a deploy (manual or CI)
deployangel check --name="smoke: signup" --status=pass --covers=registration
deployangel install kamal                   # a Kamal post-deploy hook that registers each deploy
deployangel install docker                  # bake the commit into the image as DEPLOYANGEL_REVISION
deployangel install agents                  # set up Claude Code, Cursor, and Codex in this project
deployangel doctor                          # check the setup

deployangel doctor は、このチェックアウトを確認します（プロジェクトの依存関係にエージェントが含まれているか、本番環境がリリースをどのように認識するか）。また、トークンがある場合は、DeployAngel がアプリについて把握している内容も確認します。報告を送信しているプロセスと、それぞれが実行しているリリース、エージェントが報告したルート、ジョブクラス、スケジュール済みジョブ、さらにセットアップ上の問題とそれぞれの対処方法が対象です。アプリを読み込まないため、Celery Beat、django-celery-beat、django-crontab、recurring_jobs のスケジュールは、実行中のエージェントから報告された内容に基づいて確認されます。終了コードが5になるのは、トークンが拒否された場合、サーバーに到達できない場合、依存関係にエージェントがない場合のみです。警告では終了コードが0になるため、CI でも安全に実行できます。DEPLOYANGEL_API_TOKEN を読み取り、アプリの実行環境では DEPLOYANGEL_TOKEN も読み取るため、heroku run deployangel doctor を実行すると、そのプロセスが報告しているリリースも表示されます。 出力はターミナル上ではテキスト、パイプに渡す場合は JSON です（--format=text|json）。終了コード：0 はクリア済み、1 は失敗、2 は未クリア、3 は検証中またはタイムアウト、4 はデプロイが見つからない、5 は使用方法、認証、またはネットワークのエラー、6 は初回チェック時点で問題なし（未クリア）、7 は初回チェック時点で警告ありです。GitHub Actions では、verify は判定をジョブのサマリーにも書き込みます。

コーディングエージェントでは、プロジェクト内で deployangel install agents を実行します。これにより、MCP サーバーが .mcp.json（Claude Code）、.cursor/mcp.json（Cursor）、および .codex/config.toml（Codex。信頼するプロジェクトでのみ読み込まれます）に追加され、デプロイ後に判定を待つよう指示する内容が AGENTS.md に追加されます。また、それをインポートする CLAUDE.md も追加されます。uv または Poetry のプロジェクトでは、uv run または poetry run を通じて deployangel を実行します。既存のエントリは置き換えず、再実行すると自身の指示だけを更新します。ファイルをコミットしてください。トークンは環境内に保持されます。

または、サーバーを自分で追加します。

claude mcp add deployangel -- deployangel mcp        # Claude Code (or: -- uvx deployangel mcp)

Codex の場合は、~/.codex/config.toml に追加します。

[mcp_servers.deployangel]
command = "deployangel"     # or "uvx", with args = ["deployangel", "mcp"]
args = ["mcp"]

その他の MCP クライアント（Cursor、VS Code、Zed など）でも同じコマンドを実行します。サーバーの起動時の環境に DEPLOYANGEL_API_TOKEN が必要です。

利用できるツールは get_verification、wait_for_verification、get_exercise_plan、list_deployments、get_exception、list_late_regressions、およびトークンが許可する場合の register_deployment です。いずれも本番環境を変更できません。リリースがまだクリアされていない場合、deployangel plan（または get_exercise_plan）は、クリアまでに必要な条件と、より早くクリアできるよう本番環境に対して実行すべき確認内容を示します。クリアの前提となる確認事項と、変更があり、使用頻度も低いため実行する価値があるにとどまるパスを分けて示します。データを変更するルートには印が付いています。そのようなルートにはテストアカウントを使うか、事前に確認してください。deployangel exercise --url=<production URL> は読み取り専用の処理を行います。計画に含まれるパスパラメーターのない GET ルートにリクエストを送り、未達分のリクエスト数を各ルートに振り分けます（最大 200 件、約 5 リクエスト/秒、DeployAngel-Exercise として送信）。その後、リリースに送信内容を記録し、ページ上の「Exercised from your side」に表示します。データを変更するルートやパスパラメーターが必要なルートはスキップして名前を表示し、ページで最初に 404 が返されると、そのページへのリクエストを停止して、割り当て分を応答したページに振り分けます。--dry-run を指定すると、送信予定の内容が表示されます。

コマンドとその出力は Ruby gem の deployangel コマンドと一致するため、どちらのドキュメントとエージェント向け指示も両方に適用されます。

開発

python -m venv .venv
.venv/bin/pip install -e . django djangorestframework django-celery-beat fastapi httpx flask celery rq fakeredis pytest pytest-asyncio
.venv/bin/pytest

RQ_REDIS_URL=redis://localhost:6379/15 を設定すると、実際の Redis に対して RQ のフォーク型ワーカーも実行できます。

エージェントは DeployAngel Agent Protocol v1 を使用します。プロセスごとに 1 分間に 1 回、gzip 圧縮した JSON ペイロードを POST /api/v1/telemetry に送信し、アプリケーションのメタデータをプロセスごとに 1 回 POST /api/v1/application_metadata に送信します。 これらのペイロードは src/deployangel/core/protocol.py と src/deployangel/metadata.py で生成します。