如何在不重启应用的情况下动态调整日志级别

生产排障常需临时开启 DEBUG 日志。本文介绍三种无需重启即可动态调整日志级别的方法:API 端点、UNIX 信号、配置文件热加载,并讲解如何在观测云侧配合控制采集量与成本。

最佳实践
如何在不重启应用的情况下动态调整日志级别技术指南封面

动态调整日志级别(Dynamic Log Level)是指在不重启应用的前提下,于运行时修改日志输出的最低级别。变更在哪些实例上生效,取决于配置分发与各实例是否成功应用。 它解决的痛点很实际:生产环境为控制日志量默认只开 INFO,但线上排障往往需要 DEBUG 级细节——为改级别重启服务,既中断流量又可能让问题现场消失。

核心要点速览

  • 动态调整日志级别是不重启应用、运行时修改日志级别的能力,让排障不打断服务。
  • 三种实现:API 端点(可远程自动化)、UNIX 信号(示例使用 SIGUSR2 和 SIGHUP)、配置文件热加载(Logback scan)。
  • 检查日志增量和级别字段解析,避免调试记录挤占正常日志的存储空间。
  • 三条纪律:调整留审计日志、控制采集成本、排障完调回级别。

三种主流实现方式

方法一:提供调整级别的 API 端点

最直观的思路:在内部管理入口提供受权限保护的 POST 接口。以 Django + Loguru 为例,原有应用 sink 已配置为 INFO,只为支付模块添加一个 DEBUG sink。过滤器只接收该模块的 DEBUG 事件,有效期为五分钟。这样可以避免为调整级别而移除已有 sink、序列化规则和审计配置。

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"})

在应用启动时注册一次 sink,支付模块用 payments_log 写日志。将项目定义的 ops.change_loglevel 权限授予运维角色,并保留 Django 会话认证和 CSRF 校验。POST JSON {"log_level":"DEBUG"} 可开启调试,{"log_level":"INFO"} 可提前结束。为 ops.log_level_audit 配置独立的持久化审计输出并检查写入是否成功,变更记录不能依赖临时 DEBUG sink。

两个必须注意的点:端点务必加鉴权;示例状态只在当前 worker 内有效。多进程或多实例部署时,按目标分发带过期时间的配置,并逐个核对生效结果。

方法二:利用 UNIX 信号

信号可用于改变指定进程内的日志配置。Node.js 的 SIGUSR1 保留用于启动调试器,不能直接用作普通日志开关。这个 Pino 示例只调整支付子 logger,约定 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 <进程ID>,提前恢复时执行 kill -s HUP <进程ID>。信号只到指定进程,kill 成功并不能证明日志级别已更新。逐个核对目标实例,并通过运维操作记录保留操作者与目标信息。Node.js 信号文档 · Pino 日志级别

方法三:配置文件热加载

部分框架内置"监听配置变化自动重载"能力。前提是框架监视的配置文件确实发生变更,加载成功后才会生效:

  • Logback:<configuration scan="true" scanPeriod="10 seconds"> 按间隔检查配置。可修改 <logger name="com.example.payments" level="DEBUG"/>,只扩大指定 logger 的输出;若依赖 Spring Boot 的 Logback 扩展,不可与配置扫描一起使用。Logback 配置 · Spring Boot Logback 扩展
  • Log4j2:<Configuration monitorInterval="10"> 每隔约 10 秒检查配置变化,0 关闭轮询。改完再确认各实例实际加载了新文件。Log4j 2 配置

调整后检查日志输出

先限定需要排查的实例或模块,并记录恢复原级别的时间。开启 DEBUG 后检查日志增长速度、磁盘余量和敏感字段;排障结束后在每个目标实例确认级别已经恢复。

使用观测云集中查询这些日志时,取一条新产生的 DEBUG 记录,检查 Pipeline 是否把源级别正确映射为 status,并核对时间戳。字段提取方式见 DataKit 日志采集指南;缺少级别提取会影响按严重程度筛选,而不只是展示问题。

三种方法对比

方法 优点 局限 适用场景
API 端点 可远程、易自动化 需鉴权与多实例广播 微服务、云环境
UNIX 信号 不开网络端口 需登录机器、逐实例操作 单实例或少量实例
配置热加载 零代码 依赖框架能力、生效有延迟 Java 系传统部署

总结

动态调整级别的价值在于排障不打断服务。三条纪律:调整动作留审计日志;检查各实例日志增量与存储余量;排障完成后把级别调回去。

常见问题(FAQ)

Q:临时开 DEBUG 有什么风险?
日志量暴增带来的 I/O 与存储压力,以及 DEBUG 日志可能夹带敏感信息。建议只对目标模块限时开启,检查是否输出敏感信息,用完即关。

Q:多实例下最优雅的传播方式?
配置中心(Nacos/Consul/etcd)下发最规范,所有实例监听同一配置项;简单场景用脚本广播 API 调用也可行。

Q:能只对某个模块开 DEBUG 吗?
可以。多数框架的 logger 分层组织(按包名/模块名),可只调整特定 logger,同时确认下游 sink、appender 或采集规则不会继续挡掉该级别,把日志增量控制在最小范围。


系列阅读:理解日志级别 | 微服务日志最佳实践

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

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

立即开始

选择观测云版本

代码托管平台