監視・スケーリング戦略

1. 観測対象 (SLI / SLO)

1.1 主要 SLI / SLO 一覧

1.2 取得タイミング

• リアルタイム: 推論レイテンシ / GPU・CPU / 5xx → 10 秒間隔で push
• 準リアルタイム: false positive・マスク fallback → 60 秒ウィンドウで集計
• 日次: mAP@50 / クォータ消費 → cron 03:00 JST で集計

2. メトリクス収集アーキテクチャ

2.1 全体構成図

2.2 各環境からの収集方式

2.3 Prometheus 例 (scrape config)

scrape_configs:
  - job_name: mahjong-edge
    scrape_interval: 10s
    static_configs:
      - targets:
          - jetson-01.local:9100
          - jetson-01.local:8000
          - jetson-02.local:9100
          - jetson-02.local:8000
        labels:
          env: prod
          role: edge

  - job_name: cadvisor
    static_configs:
      - targets: ['jetson-01.local:8080', 'jetson-02.local:8080']

  - job_name: cloudflare-workers-ai
    metrics_path: /probe
    static_configs:
      - targets: ['cf-exporter:9101']

2.4 各スクリプトでの structured logging

既存スクリプト (scripts/render-3d-overlay-cf.py, scripts/evaluate-agari-transition-detector.py, scripts/filter-roboflow-frames.py 等) に Python 標準 logging モジュールの JSON フォーマッタを統一導入する。

import logging, json, sys, time

class JsonFormatter(logging.Formatter):
    def format(self, record):
        payload = {
            "ts":       int(time.time() * 1000),
            "level":    record.levelname,
            "logger":   record.name,
            "msg":      record.getMessage(),
            "script":   getattr(record, "script", None),
            "model":    getattr(record, "model", None),
            "frame":    getattr(record, "frame", None),
            "latency_ms": getattr(record, "latency_ms", None),
            "fp_count":   getattr(record, "fp_count", None),
        }
        return json.dumps({k: v for k, v in payload.items() if v is not None}, ensure_ascii=False)

handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
logging.basicConfig(level=logging.INFO, handlers=[handler])
log = logging.getLogger("mahjong.edge")

log.info("inference done", extra={"script": "render-3d-overlay-cf",
                                  "model": "v2-7", "frame": 1234, "latency_ms": 28.4})

3. アラート設定 (閾値・通知先)

3.1 アラート一覧 (Alertmanager 想定)

3.2 通知チャネル設計

• Slack #mj-alerts: 全 SEV を集約。SEV1 は @here
• LINE Bot (LineClaude 経由): SEV1 のみ。代表者 (miyata@) と現地担当の LINE グループ
• PagerDuty: SEV1 の中でも「サービス停止系」 (EdgeServiceDown, PagesHttp5xxSpike) のみ on-call ローテ
• email: 日次サマリのみ (cron 09:00 JST)

4. スケーリング戦略 (1 → 10 → 100 ユーザ)

4.1 段階別構成

4.2 Cloudflare Queues + Workers AI でのリクエストキュー

// Worker (TypeScript)
export default {
  async fetch(req: Request, env: Env) {
    const body = await req.arrayBuffer();
    await env.MJ_QUEUE.send({ image: body, ts: Date.now() });
    return new Response(JSON.stringify({ status: "queued" }), { status: 202 });
  },
  async queue(batch: MessageBatch<Job>, env: Env) {
    for (const msg of batch.messages) {
      const result = await env.AI.run("@cf/mahjong-vision/mleague-tiles-v2-7", {
        image: [...new Uint8Array(msg.body.image)],
      });
      // 結果は KV / R2 に格納
      await env.RESULTS.put(`result/${msg.body.ts}`, JSON.stringify(result), {
        expirationTtl: 3600,
      });
      msg.ack();
    }
  },
} satisfies ExportedHandler<Env>;

• burst 吸収: 同時 1,000 リクエスト来ても Queue が受け、Workers AI consumer が 100 並列で順次処理
• retry: 失敗時 3 回まで自動再試行 (Queue 設定)
• 結果取得: クライアントは GET /result/:ts で polling、または Durable Objects で push 通知

4.3 Jetson クラスタ (3 台で 100 ユーザ想定)

1 Jetson Orin Nano = 30 FPS (1280×720, INT8) ≈ 30 同時ストリーム (1 FPS / ユーザ前提) を捌ける。 100 ユーザ同時を見込む場合は 3 台構成。

4.4 スケーリング発動条件 (自動 / 半自動)

5. 障害対応 Runbook (3 ケース)

詳細な markdown 版は docs/runbook-incident-response.md に。本セクションは Web で即参照できる短縮版。

# 1. サービス起動確認
systemctl status mahjong-edge

# 2. 直近 log で例外を確認
journalctl -u mahjong-edge -n 200 --no-pager | grep -E '(ERROR|Traceback)'

# 3. カメラ device 認識
ls /dev/video* && v4l2-ctl --list-devices

# 4. マスクが全黒でないか (前処理) → 直近 frame をダンプ
ls -la mleague/output/_native_bbox_check.png

# 既存ページは生きているはず
curl -s -o /dev/null -w "%{http_code}\n" https://mahjong-scorekeeping-docs.pages.dev/index.html

# 最新追加した HTML が 404 なら auto-deploy 停止確定
curl -s -o /dev/null -w "%{http_code}\n" https://mahjong-scorekeeping-docs.pages.dev/production-deployment-guide.html

npx wrangler login                  # 初回のみ
npx wrangler pages deploy docs-site/ \
    --project-name mahjong-scorekeeping-docs \
    --commit-dirty=true \
    --branch main

# 1. エラー判定
journalctl -u mahjong-edge -n 200 --no-pager | grep -E '(429|quota|rate)'

# 2. 残クォータ (web ダッシュボード) を確認
# https://app.roboflow.com//settings/usage

上記 3 ケース以外の障害分類 (SEV1/SEV2/SEV3 全体) と SLA 定義は docs/runbook-incident-response.md を参照。