Analytics Worker

Analytics worker は Enterprise 専用のアドオンです。Cockpit ダッシュボード（DORA 風メトリクス、PR ライフサイクル、LLM ベースの PR classifier）を駆動する取り込み cron を実行します。

デフォルトのインストーラーはこのワーカーを含みません。コミュニティ版のセルフホストデプロイメントには不要で、これらの変数はデフォルトの .env.example からフィルタリングされています。セルフホスト Enterprise ライセンスを持っていて、Cockpit のレポートが必要な場合のみ進めてください。

何をするか

worker と同じイメージ（kodus-ai-worker）を実行する別プロセスで、 boot 時に WORKER_ROLE=analytics で選択されます。このプロセスからのみ 2 つの cron が起動します:

取り込み（ANALYTICS_INGESTION_CRON、デフォルト */30 * * * *） — Mongo + OLTP Postgres から pull request とレビューセッションを読み、 analytics schema に投影します。
Classifier（ANALYTICS_CLASSIFIER_CRON、デフォルト */15 * * * *） — LLM を呼び出して各 PR にタイプ（feature/bugfix/refactor/etc）をタグ付けします。

メインの worker から分離することで、code review の event loop が長時間の取り込みクエリの影響を受けないようにします。

トポロジー

Analytics warehouse は別の DB ではなく Postgres の schema です。 2 つのレイアウトがサポートされています:

共有 Postgres（セルフホスト推奨） — ANALYTICS_PG_DB_HOST を空にします。設定ローダーが API_PG_DB_* 変数にフォールバックし、同じインスタンスに analytics schema を作成します。バックアップと運用は 1 つの DB だけ。
専用 Postgres — 別のインスタンスを指す ANALYTICS_PG_DB_* 全体を設定します。OLTP の write path から完全に分離した分析クエリが必要な場合に使用します。

セルフホスト Enterprise での有効化

1. `docker-compose.yml` にサービスを追加

worker-analytics:
    image: ghcr.io/kodustech/kodus-ai-worker:latest
    platform: linux/amd64
    container_name: kodus-worker-analytics
    environment:
        - ENV=production
        - NODE_ENV=production
        - WORKER_ROLE=analytics
    networks:
        - shared-network
        - kodus-backend-services
    restart: unless-stopped
    env_file:
        - .env
    depends_on:
        - db_kodus_postgres
        - db_kodus_mongodb
        - rabbitmq

イメージは worker サービスと同一です — WORKER_ROLE=analytics だけが取り込みモードに切り替えます。

2. `.env` に analytics ブロックを追加

共有 Postgres（推奨）:

# ANALYTICS_PG_DB_HOST が空 → ローダーは API_PG_DB_* を再利用し、
# メインインスタンスに `analytics` schema を作成します。
ANALYTICS_PG_DB_HOST=
ANALYTICS_PG_DB_SCHEMA=analytics

# Cron schedules (UTC).
ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *

専用 Postgres:

ANALYTICS_PG_DB_HOST=your-analytics-host
ANALYTICS_PG_DB_PORT=5432
ANALYTICS_PG_DB_USERNAME=analytics
ANALYTICS_PG_DB_PASSWORD=...
ANALYTICS_PG_DB_DATABASE=kodus_analytics
ANALYTICS_PG_DB_SCHEMA=analytics

ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *

3. Boot — マイグレーションが自動実行されます

worker-analytics コンテナは api/worker/webhooks と同じ prod-entrypoint.sh を共有します。RUN_MIGRATIONS=true（インストーラーのデフォルト）の場合、analytics warehouse のマイグレーション（yarn analytics:migration:run:prod）が初回 boot で実行され、 analytics schema とそのテーブルが作成されます。

リファレンス

変数	説明	デフォルト
`WORKER_ROLE`	このコンテナでは `analytics` に設定する必要があります。	必須
`ANALYTICS_PG_DB_HOST`	Analytics Postgres ホスト。空 → メイン Postgres を再利用。	空
`ANALYTICS_PG_DB_PORT`	Analytics Postgres ポート。	`5432`
`ANALYTICS_PG_DB_USERNAME`	Analytics Postgres ユーザー。空 → `API_PG_DB_USERNAME` を再利用。	空
`ANALYTICS_PG_DB_PASSWORD`	Analytics Postgres パスワード。空 → `API_PG_DB_PASSWORD` を再利用。	空
`ANALYTICS_PG_DB_DATABASE`	Analytics Postgres データベース。空 → `API_PG_DB_DATABASE` を再利用。	空
`ANALYTICS_PG_DB_SCHEMA`	Warehouse テーブルの schema 名。	`analytics`
`ANALYTICS_PG_POOL_MAX`	Analytics Postgres プールの上限。	`5`
`ANALYTICS_INGESTION_CRON`	取り込み実行の cron schedule（UTC）。	`/30 * * *`
`ANALYTICS_CLASSIFIER_CRON`	LLM PR タイプ classifier の cron schedule（UTC）。	`/15 * * *`

取り込みの一時停止（高度）

コンテナを削除せずに runtime で取り込みを停止するには、 ANALYTICS_INGESTION_DISABLED=true および/または ANALYTICS_CLASSIFIER_DISABLED=true を設定し、worker-analytics を再起動してください。Cron はスケジュールされたままですが、各 tick がショートサーキットします。これはインシデントトリアージ用で、長期設定としては使わないでください — これらの変数は主にクラウド向けに管理されており、インストーラーテンプレートには表示されない場合があります。

動作の確認

Boot 後、analytics worker のログを追跡します:

docker compose logs -f worker-analytics

30 分ごとに analytics ingestion done in NNNms — {...} のような行と、 15 分ごとに analytics classifier done ... が表示されるはずです。表示されない場合は、WORKER_ROLE=analytics がこのコンテナにのみ設定されていることを確認してください（メインの worker には設定しないこと — そちらは code-review のままにする必要があります）。

概念

ローカルクイックスタート

Dockerでデプロイ

Kubernetes でデプロイ

Gitプロバイダーの設定

Analytics Worker

何をするか

トポロジー

セルフホスト Enterprise での有効化

1. `docker-compose.yml` にサービスを追加

2. `.env` に analytics ブロックを追加

3. Boot — マイグレーションが自動実行されます

リファレンス

取り込みの一時停止（高度）

動作の確認

​何をするか

​トポロジー

​セルフホスト Enterprise での有効化

​1. docker-compose.yml にサービスを追加

​2. .env に analytics ブロックを追加

​3. Boot — マイグレーションが自動実行されます

​リファレンス

​取り込みの一時停止（高度）

​動作の確認

何をするか

トポロジー

セルフホスト Enterprise での有効化

1. `docker-compose.yml` にサービスを追加

2. `.env` に analytics ブロックを追加

3. Boot — マイグレーションが自動実行されます

リファレンス

取り込みの一時停止（高度）

動作の確認