再起動せずにログレベルを動的に変更する方法

管理 API、Unix シグナル、設定の再読み込みで対象のログレベルだけ一時的に変更し、調査後に元へ戻す方法を解説します。

ベストプラクティス
ログ、メトリクス、トレースを示すイラスト

同じワーカーで決済リクエストが続けてタイムアウトしたとします。通常の INFO ログで対象のリクエストは分かっても、調査に必要な上流サービスの応答時間が残っていません。そのワーカーの決済ロガーだけ一時的に DEBUG に切り替え、再発時の記録を取ったら元に戻します。全インスタンスのログを増やすと、探しているリクエストがかえって見つけにくくなります。

アプリケーションを再起動せずにログレベルを変更する方法には、認証付きの管理 API、シグナル、ログ設定の再読み込みがあります。管理 API がワーカー内の値を更新する実装なら、変更はリクエストを処理したワーカーに限られます。Unix シグナルは指定したプロセスに届き、設定ファイルの変更は、そのファイルを監視して正常に読み込んだインスタンスで有効になります。

管理 API に有効期限を設ける

Django と Loguru の例です。通常の出力先は INFO の設定を保ち、ワーカーの起動時に DEBUG 専用の出力先を一つ追加します。決済コンポーネントの DEBUG イベントだけを対象にし、ワーカー内の期限を過ぎたらフィルターで止めます。既存の出力先やフォーマット設定はそのまま使えます。

import json
import logging
import sys
import time
from threading import Lock

from django.contrib.auth.decorators import permission_required
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_protect
from django.views.decorators.http import require_POST
from loguru import logger

audit = logging.getLogger("ops.log_level_audit")
lock = Lock()
debug_until = 0.0
payments_log = logger.bind(component="payments")

def debug_filter(record):
    if (record["level"].name != "DEBUG"
            or record["extra"].get("component") != "payments"):
        return False
    with lock:
        return time.monotonic() < debug_until

logger.add(sys.stderr, level="DEBUG", filter=debug_filter)

@require_POST
@csrf_protect
@permission_required("ops.change_loglevel", raise_exception=True)
def change_log_level(request):
    global debug_until
    try:
        payload = json.loads(request.body)
    except (ValueError, UnicodeError):
        return JsonResponse({"error": "Invalid JSON"}, status=400)
    level = payload.get("log_level") if isinstance(payload, dict) else None
    if level not in ("INFO", "DEBUG"):
        return JsonResponse({"error": "Expected INFO or DEBUG"}, status=400)

    with lock:
        if level == "INFO":
            debug_until = 0.0
        elif time.monotonic() >= debug_until:
            debug_until = time.monotonic() + 300
    audit.warning("actor=%s component=payments requested=%s", request.user.pk, level)
    return JsonResponse({"requested": level, "scope": "current worker"})

決済モジュールでは payments_log でログを書きます。Django プロジェクトで ops.change_loglevel 権限を定義し、運用担当者に付与します。セッション認証と CSRF 検証が有効な POST で {"log_level":"DEBUG"} を送ると、5 分間だけ DEBUG ログを出力します。途中で止めるには {"log_level":"INFO"} を送ります。有効期間中に DEBUG を再指定しても期限は延びません。監査ログは専用の永続化先に送り、操作履歴が実際に届くことも確認します。

複数ワーカーをロードバランサーの背後に置くと、操作するたびに違うワーカーへ届くことがあります。対象を明示できる運用経路で設定を配るか、有効期限付きの設定を配信し、各インスタンスの適用状況を確かめます。 Django の権限 · Django の CSRF 保護 · Loguru のハンドラー設定

対象プロセスにシグナルを送る

運用経路が確立されている小規模な Unix サービスなら、シグナルで切り替える方法もあります。Node.js では SIGUSR1 がデバッガーの起動に使われます。この Pino の例では、SIGUSR2 で決済用の子ロガーだけ DEBUG に切り替え、SIGHUP またはタイムアウトで元のレベルへ戻します。

const pino = require("pino");

const appLog = pino({ level: "info" });
const paymentsLog = appLog.child({ component: "payments" });
const baseline = paymentsLog.level;
let expiry;

function restoreLevel() {
  if (!expiry) return;
  clearTimeout(expiry);
  expiry = undefined;
  paymentsLog.level = baseline;
  appLog.info({ levelRestored: baseline }, "payments debug disabled");
}

process.on("SIGUSR2", () => {
  if (expiry) return;
  paymentsLog.level = "debug";
  expiry = setTimeout(restoreLevel, 300_000);
  expiry.unref();
  appLog.info("payments debug enabled for 5 minutes");
});
process.on("SIGHUP", restoreLevel);

ハンドラーの登録後、対象のプロセスに kill -s USR2 <pid> を実行します。早めに戻す場合は kill -s HUP <pid> を実行します。アプリケーションやプロセス管理ツールで同じシグナルを別の用途に割り当てていないことを確認してください。コマンドの成功だけでレベルの変更は確認できません。対象の出力を確かめ、誰がどのプロセスを操作したかを運用記録に残します。ロガーが DEBUG を出力しても、後段の転送フィルターで破棄される場合があります。 Node.js のシグナル · Pino のログレベル

フレームワークが監視している設定を更新する

Logback では scan="true" を設定し、scanPeriod="10 seconds" のように間隔の単位も指定します。com.example.payments のような名前付きロガーを指定すれば、対象パッケージを絞れます。Spring Boot の Logback 拡張機能と Logback の設定スキャンは併用できません。Log4j 2 の monitorInterval="10" は 10 秒ごとの変更確認を指定し、0 はポーリングを無効にします。各インスタンスが変更後のファイルを参照し、正常に再読み込みしたことを確認します。調査を終えたら以前の設定を戻します。 Logback の設定 · Spring Boot の Logback 拡張 · Log4j 2 の設定

必要なログが保存先に届いたか確かめる

DEBUG を有効にしたら、対象サービスとインスタンスで新しいレコードを一件探します。DataKit で収集している場合は、Pipeline が元の重大度を status に割り当て、イベント発生時刻を保持しているかを確認します。アプリケーションが出力できていても、収集側で除外されたり、重大度を誤って解析されたりすることがあります。データ量がどれだけ増えたか、認証情報やリクエストのペイロードが出力されていないかも確認します。元に戻した後は、その対象から新しい DEBUG イベントが出なくなったことを確かめます。 DataKit ログ収集

調査記録には変更時刻、対象、有効期限を残します。デバッグイベントのフィールド構成については、ログフォーマットのベストプラクティスを参照してください。

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ