如何在不重新啟動應用程式的情況下動態調整日誌級別

透過受保護的管理 API、Unix 訊號或重新載入設定,在指定的 worker 暫時開啟 DEBUG,並在排查後恢復原本的級別。

最佳實務
日誌、指標與追蹤三類可觀測訊號示意圖

假設同一個 worker 有兩筆付款請求逾時。平常的 INFO 日誌能找到請求,卻沒有記下排查需要的上游回應時間。只在該 worker 的付款 logger 暫時開啟 DEBUG,等問題再次出現並留下記錄,再恢復原本的級別。整批執行個體一起提高詳細度,反而可能讓目標請求更難找。

應用程式無須重新啟動,也可以透過已驗證身分的管理 API、訊號處理器或重新載入日誌設定來調整日誌級別。三種方式的生效範圍各有不同。管理 API 若只更新程序內記憶體,變更就只在收到請求的 worker 生效。Unix 訊號只送到指定程序。修改設定檔後,也只有監看並成功重新載入該檔案的執行個體會套用。

為管理 API 設定有效期限

以 Django 和 Loguru 為例,原有應用程式輸出端維持 INFO。每個 worker 啟動時加上一個 DEBUG 專用輸出端,只接收標記為付款元件的 DEBUG 事件。worker 內的期限一到,篩選器便會擋下這些事件,既有輸出端和格式設定照常運作。

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"},即可開啟五分鐘的除錯時段。送出 {"log_level":"INFO"} 可提前結束,有效期間重送 DEBUG 不會延長期限。把稽核 logger 接到獨立的持久化儲存端,並確認變更記錄確實寫入。

部署多個 worker 時,一般負載平衡的請求每次可能到不同的 worker。可使用能指定目標的管理管道,或分發附有效期限的設定,再逐一確認執行個體是否套用。 Django 權限 · Django CSRF 防護 · Loguru 處理器設定

把訊號送到指定程序

已有維運操作管道的小型 Unix 服務,也可透過訊號切換。Node.js 的 SIGUSR1 保留給偵錯工具。這個 Pino 範例使用 SIGUSR2 將付款子 logger 切為 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>。先確認這兩個訊號在應用程式和程序管理工具中沒有其他用途。命令成功後仍需查看該程序的輸出,並在維運記錄中留下操作者與目標。logger 發出 DEBUG 事件之後,下游傳輸篩選器仍可能將它捨棄。 Node.js 訊號事件 · Pino 日誌級別

更新框架實際監看的設定檔

Logback 可啟用 scan="true",再用 scanPeriod="10 seconds" 明確指定間隔和單位。只修改 com.example.payments 這類具名 logger,就能把範圍限在所需的套件。設定掃描無法和 Spring Boot 的 Logback 擴充功能併用。Log4j 2 的 monitorInterval="10" 會每十秒檢查變更,0 會關閉輪詢。確認各執行個體都能讀到新檔案並成功重新載入,排查結束後再還原先前的設定。 Logback 設定 · Spring Boot Logback 擴充 · Log4j 2 設定

確認需要的日誌有抵達儲存端

開啟 DEBUG 後,從目標服務和執行個體找一筆新記錄。若以 DataKit 採集,確認 Pipeline 已將來源的嚴重程度對應至 status,並保留事件發生時間。應用程式可以正常輸出,但採集端仍可能丟棄事件或解析錯誤的級別。也要查看資料量增幅,以及日誌是否帶有憑證或請求內容。恢復原級別後,確認目標已停止產生新的 DEBUG 事件。 DataKit 日誌採集(簡體中文)

調查記錄應一併保存變更時間、目標與有效期限。若要設計除錯事件的欄位,可參考日誌格式化最佳做法。

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台