CHAPTER 08 / KOHAKU

ログ・監視・停止

アプリ応答、ヘルス、メトリクス、ログを組み合わせて状態を確認し、プロセスを停止します。

管理ポートを有効にする

conf/server.yaml

management:
  port: 9090
  host: "127.0.0.1"
  maxConnections: 16

管理エンドポイント — GET / HEAD
パス	200の意味	非200の代表理由
/health/started	初回起動が完了した。一度UPになるとDOWNへ戻らない	starting
/health/ready	起動完了かつ停止中でなくServerがSTARTED	starting / stopping / 状態名
/health/live	ServerがFAILEDでなくアプリコネクタのacceptループが生存	failed / accept-loop
/metrics	Prometheusテキスト形式0.0.4で都度採取	採取例外はHTTP層の500

観測の例

curl -i http://127.0.0.1:9090/health/started
curl -i http://127.0.0.1:9090/health/ready
curl -i http://127.0.0.1:9090/health/live
curl -fsS http://127.0.0.1:9090/metrics

ヘルス本文は UP または DOWN 理由 の1行です。停止に入るとreadinessはDOWN stoppingとなり、livenessはacceptループ停止を故障として扱いません。管理面が閉じた後は応答しません。webapp配備失敗やDB疎通、過負荷の判定は現行の組込みreadinessには含まれません。必要なアプリURLも個別に確認します。

GET/HEADの未知パスは404、認識済みのGET/HEAD以外は405（Allow: GET, HEAD）、未知メソッドは501です。メソッドをパスより先に判定するため、未知パスへのPOSTも405です。管理面はアクセスログを出さず、本文を想定しません。アプリ向けhttp.*の期限を継承せず、read/write等は内部定数5秒です。

メトリクス・JMX・JFR

metricsにはHTTP、JVM、webapp、接続プール、トランザクション、管理タスク、WebSocket、診断等の値が登録されます。ラベルの意味は実際のHELP行と値を確認してください。メトリクスは再起動を跨いで永続化されません。

Platform MBeanServerには kohaku:server=<連番>,type=Server、Context、Connector、Metricsを登録します。Serverの状態・稼働時間、Contextの状態・セッション数、Connectorの接続数、メトリクスのスナップショットを確認できます。リモートJMXを開く設定を自動では行いません。JFRにはHTTP要求と診断イベントを連携します。

コンテナログ

conf/logging.yaml は最初のロガー取得前にMainがパスを指定します。別ファイルを使う場合は KOHAKU_JAVA_OPTS で -Dkohaku.logging.config=/absolute/path/logging.yaml を渡します。

conf/logging.yaml — ファイル出力とコンソール

level: INFO
level.kohaku.http: WARNING
target: "logs/kohaku.log"
console: true
captureStdio: true
rotate:
  maxBytes: 10485760
  every: "1d"
  keep: 10
async:
  enabled: false
  queueSize: 8192
  drainTimeoutMillis: 5000

logging.yamlの全設定系統
キー	既定	意味
level	INFO	TRACE/DEBUG/INFO/WARNING/ERROR/OFF。不正名はINFOへ
level.<ロガー接頭辞>	未指定	最長一致の接頭辞で上書き
target	stderr	ファイルパス指定でファイルにも出力。相対パスはスクリプト起動時の配布ルート基準
console	true	本物の標準エラーに短縮形式で出力
captureStdio	true	System.outをINFO、System.errをWARNとして行単位に捕捉
rotate.maxBytes	0	非負。0はサイズトリガ無効
rotate.every	空文字	正整数+d/h/m。空は期間トリガ無効
rotate.keep	10	正数。保持世代
async.enabled	false	有界キュー経由で出力。ERRORは同期
async.queueSize	8192	正数。レコード数
async.drainTimeoutMillis	5000	非負・ミリ秒。待機超過の残りは停止スレッドが同期出力

ファイル出力はUTC ISO-8601・32桁相関ID・ロガーFQCN、コンソールは短縮形式です。非同期出力は満杯でも同期出力して行を失わない設計ですが、出力順が発行順と異なり得ます。診断イベントバスは別方針で、配送キュー満杯ではイベントを落として件数を記録します。

アクセスログ

conf/server.yaml

accesslog:
  enabled: true
  file: "logs/access.log"
  rotate:
    maxBytes: 10485760
    every: "1d"
    keep: 10
requestId:
  acceptIncoming: false
  responseHeader: "X-Request-Id"

アクセスログは既定で無効です。開けない場合はWARNし、アクセスログ無効のまま起動します。logging.yaml のrotateはコンテナログ、server.yaml のaccesslog.rotateはアクセスログです。kohaku.out は起動スクリプトが追記する標準出力・標準エラーの保存先で、このローテーション設定では回りません。

診断成果物と異常終了

ローテーション世代の総量と空き容量閾値は diagnostics.* で調整します。空き容量不足で成果物を作れない場合、ローテーションを諦めて現用ログへの追記を続け得ます。この予算はディスク全体や現用ログの絶対的な容量上限ではありません。

起動時に logs/kohaku.running、正常停止時に logs/kohaku.clean-shutdown を使い、次回起動で前回の異常終了を報告します。常駐エージェントは lib-agent/kohaku-agent.jar が読める場合に装着し、装着されていなくてもサーバは縮退して起動します。自動再起動を行うwatchdog（OPS-W/banken）は現行の完成機能として扱いません。

停止と再起動

配布ディレクトリで実行

bin/kohaku.sh stop
bin/kohaku.sh start

起動スクリプトの環境変数
変数	既定	用途
KOHAKU_JAVA_HOME	/opt/java/jdk21	実行用JDK
KOHAKU_JAVA_OPTS	空	空白区切りのJVMオプション
KOHAKU_START_TIMEOUT	5	正整数・秒。起動直後の生存確認
KOHAKU_STOP_TIMEOUT	60	正整数・秒。SIGTERM後の終了待ち

stopはPIDと起動記録のnonceを実プロセスの引数と照合してからSIGTERMを送ります。管理ポートは停止APIではありません。終了期限超過だけでSIGKILLは送りません。stop --force は同一性確認を省略する脱出口なので、対象プロセスを運用者が確認した場合だけ使います。

サーバ停止では受付の停止、webapp停止、タスク・トランザクション・プール・Upgrade接続の回収が行われます。無期限に停止できないアプリ処理を安全に強制終了する保証はありません。警告とquarantineを確認します。停止済みServerの同一インスタンスを再起動できないため、再起動は新しいプロセスで行います。