メインコンテンツまでスキップ

運用ガイド

概要​

Yabanin は、3 つのサービスからなるシステムです。

サービス役割既定ポート
gatewayHTTP API プロキシ + 経路8082 / 9090
admin管理パネル + 利用分析 API8086
loggerdイベント取り込み → Postgres ライター8085

モジュール: github.com/reireirei/yabanin

Go バージョン: 1.25.0

ビルド: モノレポのルートから go build ./...。


サービスエンドポイント​

ゲートウェイ(pkg/gateway/gateway.go)​

アドレス目的
:8082HTTP API(転送プロキシ)
:9090管理サーバー(メトリクス、トレース)
  • ヘルス: GET http://localhost:8082/healthz — Redis の接続状態を含む JSON を返します。
  • メトリクス: GET http://localhost:9090/metrics — Prometheus の exposition 形式です。
  • トレース: OTLP/HTTP エクスポータです。環境変数で設定します(下記を参照)。

Admin サービス(services/admin/cmd/main.go)​

アドレス目的
:8086HTTP API(管理 + 利用分析)
  • ルート: /auth/*、/api/analytics/*
  • ヘルス: GET http://localhost:8086/health — 200 で "ok" を返します。
  • メトリクス: GET http://localhost:8086/metrics — Prometheus の exposition 形式です。
  • ポートの上書き: 設定キー listen_addr で設定します。

Loggerd サービス(services/loggerd/cmd/main.go)​

アドレス目的
:8085HTTP API(イベント取り込み)
  • ヘルス: GET http://localhost:8085/healthz — 200 OK を返します。
  • トレース: OTLP/HTTP エクスポータです。環境変数で設定します(下記を参照)。

ヘルスチェック​

サービスエンドポイント応答確認する依存関係
ゲートウェイGET /healthzJSON: {"status":"ok","redis":{"status":"up"}} または "down"Redis の接続
AdminGET /healthプレーンテキスト: okなし
LoggerdGET /healthzHTTP 200 OKなし

ゲートウェイのヘルス詳細​

ゲートウェイのヘルスエンドポイントは、Redis へ PING を実行します。応答には次が含まれます。

{
"status": "ok",
"redis": {
"status": "up"
}
}

Redis に到達できない場合、redis.status フィールドは "down" になり、全体のステータスは劣化した状態を反映します。これは、Kubernetes の liveness/readiness プローブや、ロードバランサのヘルスチェックに有用です。


メトリクス​

すべてのメトリクスは、Prometheus client-go(github.com/prometheus/client_golang/prometheus)を介して、サブシステム gateway の下に登録されます。各サービスの /metrics エンドポイントで、標準の Prometheus exposition 形式として公開されます。

リクエストメトリクス(ゲートウェイ)​

メトリクス型ラベル説明
gateway_requests_totalカウンタmethod、path、status処理した HTTP リクエストの合計
gateway_request_duration_secondsヒストグラムmethod、path、statusリクエストのレイテンシ(秒)
gateway_upstream_first_token_secondsヒストグラムprovider、modelストリームされた最初のトークンまでの時間(SSE リクエストのみ。バケットは 0.005 秒〜10 秒)
gateway_upstream_requests_totalカウンタprovider、model、status経路決定後の上流リクエスト
gateway_retry_totalカウンタattempt、statusモデル内のリトライ(トランスポート/429/5xx)。試行番号ごと
gateway_fallback_totalカウンタfrom、to、reasonフォールバックチェーンにおけるホップの完了
cache_hits_totalカウンタtype、org_id種類ごとの応答キャッシュ検索(exact/semantic/miss。ミスを含む)

先頭トークンのヒストグラムと、リトライ/フォールバックのカウンタは、request_logs(マイグレーション 0011)に保存される first_token_ms、attempt_count、retry_count の各列を支え、管理のリクエストエクスプローラー(/api/organizations/{id}/requests[/stats])に表示されます。

Loggerd のメトリクス​

メトリクス型ラベル説明
gateway_events_in_flightゲージ(なし)現在処理中のメッセージ数
gateway_events_consumed_totalカウンタevent_type正常に消費されたイベントの合計

events_consumed_total のイベント型:

  • request.completed — 成功したプロキシリクエストが記録された
  • request.failed — 失敗したプロキシリクエストが記録された
  • Redis ストリームの event_type フィールドからの、その他の文字列(汎用イベント)

サーキットブレーカーのメトリクス(ゲートウェイ)​

メトリクス型ラベル説明
gateway_circuit_stateゲージ(なし)現在のサーキットブレーカーの状態(下記を参照)
gateway_circuit_failuresカウンタ(なし)サーキットブレーカーがトリップしたイベントの合計
gateway_circuit_recoveriesカウンタ(なし)サーキットブレーカーが回復したイベントの合計

サーキットブレーカーの状態(ゲージ上の整数値として符号化):

  • 0 — CLOSED: 通常動作です。リクエストは通過します。
  • 1 — OPEN: サーキットがトリップしています。リクエストは転送せずに拒否されます。
  • 2 — HALF_OPEN: プローブのリクエストが許可されます。成功すると CLOSED へ遷移します。

トレース​

ゲートウェイと Loggerd の両サービスは、OpenTelemetry による分散トレースをサポートします。

設定​

環境変数説明既定
YABANIN_OTEL_ENDPOINTOTLP/HTTP エンドポイントの URL(例: http://localhost:4318)(無効)
YABANIN_OTEL_SAMPLE_RATEトレースのサンプリング率。[0.0, 1.0] の範囲の浮動小数1.0

エクスポータ​

  • プロトコル: OTLP/HTTP(gRPC ではない)
  • トレースパッケージ(pkg/tracing)は、otlptracehttp エクスポータを初期化し、グローバルな TracerProvider を登録します。
  • スパンのサンプリングは、設定されたサンプル率を使い、TracerProvider のレベルで適用されます。

コードでの使い方​

サービスは、起動時にトレースの初期化関数を呼び出します。

// Gateway (pkg/gateway/gateway.go)
if err := tracing.Init(ctx, logger); err != nil {
// log warning but do not fail startup
}

// Loggerd (services/loggerd/cmd/main.go)
if err := tracing.Init(ctx, logger); err != nil {
// log warning but do not fail startup
}

Admin サービスには、トレースの計装がありません。


応答キャッシュの動作​

検索順序​

  1. Redis の完全一致 — リクエストボディの SHA-256(キーには組織 + モデルが含まれます)。
  2. pg の完全一致(オプトイン、YABANIN_CACHE_PG_EXACT_LOOKUP) — Redis を失った後の Postgres フォールバック。
  3. セマンティック — cache_entries の埋め込みに対する pgvector の ANN 検索。

クライアントは、リクエストごとに Cache-Control: no-store を使い、検索と保存を迂回できます。

類似度の意味​

pgvector の <=> はコサイン距離(1 − 類似度、範囲 0..2)です。ゲートウェイは、X-Cache-Similarity をコサイン類似度 = 1 − distance(範囲 −1..1)として報告します。エントリがヒットになるのは、類似度 ≥ しきい値(既定 0.95、つまり距離 ≤ 0.05)のときだけです。完全一致のヒットは 1.0000 を報告します。ジャンクなプロンプトがしきい値を超えて得点することはあってはなりません。ログ/メトリクスで X-Cache-Similarity の値が 1 より大きい場合は、距離反転の修正より古いビルドであることを示します。

ストリーミングクライアント​

stream: true のリクエストに対するキャッシュヒットは、正規の chat.completion.chunk SSE フレーム(Content-Type: text/event-stream、data: ... 行、終端の data: [DONE])として再生されます。OpenAI 互換の SDK からは、通常のストリームに見えます。キャッシュヒットには X-Cache: EXACT|PG_EXACT|SEMANTIC が付きます。

ストリームされた応答から保存されるもの: 最初に解析できる完了フレームであり、最終フレームの usage オブジェクトを引き継ぎます。不正なキャッシュエントリはミスとして扱われ(リクエストは新規に処理されます)、壊れたまま再生されることはありません。

節約の意味​

request_logs.counterfactual_cost_usd は行ごとの節約の基準であり、リクエストがどのように処理されたかに依存します。

リクエストの分類反事実の基準
キャッシュヒットキャッシュされた完了の価格付き使用量(そのリクエストが上流でかかったであろうコスト)。使用量が不明なときは 0
ティア経路(分類器が処理)クライアントが要求したモデルでの価格付き使用量(routing_decision.from)
それ以外実際の支出(最適化がなければ、節約は主張しません)

ダッシュボードを解釈するときの帰結:

  • 節約率は (SUM(counterfactual) − SUM(actual)) / SUM(counterfactual) です。基準が不明な行は 0/0 として寄与します。節約を作り上げるのではなく、0 の方向へ薄めます。
  • 負の経路節約には意味があります。分類器が、クライアントの要求より高いモデルへ経路を振ったということです。
  • ティア経路(したがって経路の節約)には、組織の routing_mode が disabled 以外であることが必要です。
  • 画面によって見方が異なります。節約レポートは、上位モデルを model_requested でグループ化します(リクエストごとの結果。経路後の支出は、クライアントが求めたモデルに載ります)。コストレポートは model_used でグループ化します(実際に処理したモデルへの支出の帰属)。

リクエストをタスクにまとめる​

リクエストは、呼び出し元によって論理的なタスクへグループ化されます。X-Yabanin-Task ヘッダーを送ります(形式は [A-Za-z0-9._:-]{1,128}。無効な値は 400 で拒否されます。YABANIN_TASK は、ヘッダーのない呼び出し元に対する導入レベルの既定を設定します)。詳細とコミットごとのトレーラー: docs/agent-governance.md。

タスクグループを分析する場所: タスク画面(タスクごとのコスト / 反事実 / 節約、CSV エクスポート)と、リクエストエクスプローラーの タスク フィルタ(テーブルと統計ストリップを 1 つのタスクに限定します。スコープは URL の一部なので、フィルタしたビューは共有できます)。

ツール呼び出し​

モデルが要求するツール/関数呼び出しには、2 つの見方があります。

  • リクエストごと — エクスプローラーのインスペクタは、保存された応答サンプルを解析します(非ストリーミングの完了と、ストリームされた SSE サンプルの両方。delta の断片は、読みやすい 1 つの呼び出しへ再構成されます)。引数は、保存されたとおりに表示されます。プライバシーモードはそれらをマスクします。
  • リクエスト横断 — ツール呼び出し画面は、loggerd が同じサンプルから埋める tool_calls テーブルを集計します。合計、シェアと最終使用時刻を持つ上位ツール、モデルごとの使用量(組織スコープ、30 日のウィンドウ)です。行が存在するのは、解析できた呼び出しだけです。切り詰められた、または解析できないサンプルは不在として読まれ、使用量ゼロとしては読まれません。過去のストリームされたサンプル(テーブル化より前)はバックフィルされておらず、インスペクタ専用のままです。

設定変数​

環境変数​

変数サービス説明既定
YABANIN_OTEL_ENDPOINTゲートウェイ、LoggerdOTLP/HTTP トレースエクスポータのエンドポイント(無効)
YABANIN_OTEL_SAMPLE_RATEゲートウェイ、Loggerdトレースのサンプリング率(0.0–1.0)1.0
LISTEN_ADDRAdminHTTP の待受アドレス(例: :8086):8086

Redis Streams の設定(Loggerd)​

定数値説明
consumerGrouploggerd-workersRedis Streams のコンシューマグループ名
consumerNameloggerd-0グループ内のコンシューマ識別子
batchSize100XREADGROUP 呼び出しごとの最大メッセージ数
idleTimeout1000ms空のストリームに対するブロック時間
defaultStreamevents:queue既定の Redis ストリーム名
maxRetries3DLQ へ移すまでのリトライ回数
dlqTTL7dリトライカウンタのキーに対する TTL
pelReclaimTimeout5mPEL の古いメッセージを回収する間隔
msgSeenTTL24h重複排除キーの有効期限

DLQ(デッドレターキュー)​

  • ストリーム名: events:queue:dlq
  • maxRetries を超えたメッセージは、フィールド original_stream、retry_count、error、および元のメッセージのすべての値とともに、ここへ移動されます。
  • リトライカウンタのキーは、パターン dlq:retry:{stream}:{group}:{msg_id} に従い、TTL は 7 日です。

PEL(保留エントリリスト)の回収​

5 分ごとに、loggerd はコンシューマグループの保留エントリを走査し、アイドル時間が 5 分を超えるメッセージを、XCLAIM によって "reclaimer" コンシューマへ回収します。回収したメッセージが、その後の処理でも失敗すると、DLQ へ送られます。


ランブック​

サービスが起動しない​

  1. ログを確認する。初期化エラー(Redis 接続、DB プール)がないかを見ます。
  2. 環境変数を確認する — トレースを使う場合、YABANIN_OTEL_ENDPOINT と YABANIN_OTEL_SAMPLE_RATE が期待される形式に従っていることを確認します。
  3. ポートの衝突を確認する: 各サービスは別々のポートにバインドします(ゲートウェイ 8082/9090、admin 8086、loggerd 8085)。

ゲートウェイのヘルスが失敗する​

  1. curl http://localhost:8082/healthz — 応答の JSON を確認します。

redis.status が "down" の場合:

  • ゲートウェイのホストから、Redis が稼働し到達できることを確認します。
  • 設定内の Redis 接続パラメータ(ホスト、ポート、パスワード)を確認します。
  • ゲートウェイと Redis の間のネットワーク/ファイアウォールの問題を探します。

リクエストレイテンシが高い​

gateway_request_duration_seconds を Prometheus で問い合わせます。

histogram_quantile(0.95, rate(gateway_request_duration_seconds_bucket[5m]))
  1. method と path のラベルでフィルタし、遅いエンドポイントを特定します。
  2. 上流サービスの健全性を確認します。ゲートウェイは、設定されたバックエンドへリクエストを転送します。

イベントが Postgres に現れない(Loggerd)​

  1. ヘルスを確認する: curl http://localhost:8085/healthz

Redis ストリームにメッセージがあることを確認する:

redis-cli XRANGE events:queue - + COUNT 10

コンシューマグループの状態を確認する:

redis-cli XINFO CONSUMERS events:queue loggerd-workers

停滞したメッセージがないか、保留エントリを確認する:

redis-cli XPENDING events:queue loggerd-workers
  1. Postgres の接続を確認する — loggerd サービスは、request_logs を挿入するために DB プールを必要とします。
  2. ログを調べる。XREADGROUP のエラー、または XACK の失敗がないかを見ます。

メッセージが保留エントリリスト(PEL)に滞留する​

メッセージは、コンシューマへ配信されたが確認応答(XACK)されていないときに、PEL に蓄積します。loggerd サービスは、5 分ごとに古いメッセージを自動で回収します。

大きなバックログが見える場合:

  1. ログのアプリケーションエラー(例: DB の書き込み失敗)を確認します。
  2. Postgres が接続を受け付け、十分な容量があることを確認します。

処理が 3 回のリトライの後に失敗したメッセージは、DLQ(events:queue:dlq)へ移動されます。DLQ を調べます。

redis-cli XRANGE events:queue:dlq - + COUNT 10

サーキットブレーカーのトリップ​

gateway_circuit_state が 1(OPEN)の場合:

  1. 上流サービスが不健全であるか、高いエラー率になっている可能性が高いです。
  2. 上流サービスの健全性を直接確認します。
  3. トリップ回数の合計について、gateway_circuit_failures カウンタを監視します。
  4. サーキットが HALF_OPEN(2)へ遷移すると、プローブのリクエストが送られます。成功すると閉じます(0)。

DLQ の調査​

ポイズンメッセージを見るには、次を実行します。

redis-cli XRANGE events:queue:dlq - + COUNT 50

各 DLQ エントリには、original_stream、retry_count、error、および元のメッセージのすべてのフィールドが含まれます。メッセージは、DLQ ストリームから読み取り、メインストリームへ再発行することで再処理できます。または、根本原因を修正し、システムが通常の処理を再開するのに任せます。


アラートの推奨​

Prometheus ルールの例​

# Gateway requests exceeding 95th percentile 2s latency over 5 minutes
- alert: HighRequestLatency
expr: histogram_quantile(0.95, rate(gateway_request_duration_seconds_bucket[5m])) > 2
for: 5m
labels:
severity: warning

# Circuit breaker open
- alert: CircuitBreakerOpen
expr: gateway_circuit_state == 1
for: 0m
labels:
severity: critical

# Events queue backlog (in-flight > threshold)
- alert: HighEventBacklog
expr: gateway_events_in_flight > 500
for: 5m
labels:
severity: warning

# Event consumption rate drops to zero
- alert: NoEventsConsumed
expr: rate(gateway_events_consumed_total[5m]) == 0 and gateway_events_in_flight == 0
for: 10m
labels:
severity: critical

# Circuit breaker failure rate increasing
- alert: CircuitBreakerTrippingFrequently
expr: increase(gateway_circuit_failures[1h]) > 5
for: 0m
labels:
severity: warning

ログレベル​

すべてのサービスは、Go の log/slog を使います。本番の導入は、INFO レベルで実行してください。ログレベルは、環境変数 SLOG_LEVEL(または同等の slog ハンドラ設定)で設定します。

  • DEBUG: 冗長なメッセージレベルの詳細です。DLQ のデバッグに有用です。
  • INFO: サービスのライフサイクルイベントと、成功した操作です。
  • WARN: 回復可能な問題です(XACK の警告、重複排除の SETNX 失敗)。
  • ERROR: 対応が必要な失敗です(DB の書き込みエラー、Redis 接続の喪失)。

Docker イメージ​

イメージベースダイジェスト説明
golang:1.25.0-alpine3.22@sha256:...Go のビルドイメージ
alpine:3.22@sha256:...ランタイム(マルチステージ)

Docker イメージは、GitHub Actions のワークフロー(.github/workflows/ci.yml)の中で、SHA-256 ダイジェストによりピン留めされています。正確なダイジェストと再ビルド日は、ワークフローファイルを参照してください。


CI/CD​

GitHub Actions のワークフロー​

ワークフロートリガー説明
ci.ymlmain への push、PRビルド、リント、テスト、Docker の push
vulncheck.yml毎週(月曜 00:00 UTC)依存関係に対する govulncheck

Dependabot​

依存関係の更新は、2 つのエコシステムを持つ Dependabot で管理されます。

  • gomod: 週次のスケジュールです。パッチバージョンは自動マージされます。
  • docker: 週次のスケジュールです。パッチバージョンは自動マージされます(イメージはダイジェストでピン留め)。

クイックリファレンス​

# Run all services locally (requires Redis + Postgres)
go run ./cmd/yabanin gateway
go run ./services/admin/
go run ./services/loggerd/

# Health checks
curl http://localhost:8082/healthz # Gateway
curl http://localhost:8086/health # Admin
curl http://localhost:8085/healthz # Loggerd

# Metrics
curl http://localhost:9090/metrics # Gateway admin server
curl http://localhost:8086/metrics # Admin service

# Redis DLQ inspection
redis-cli XRANGE events:queue:dlq - + COUNT 10