Python
# -*- coding: utf-8 -*-
"""
HY Memory - 日志系统配置
标准 Python logging + TimedRotatingFileHandler,
每天一个文件,保留 15 天。支持 request_id 注入,
可按 request_id grep 日志过滤完整请求链路。
Usage:
from hy_memory.utils.log_setup import setup_logging, set_request_id
setup_logging() # 应用启动时调用一次
set_request_id("abc123def456") # 每个请求入口设置
日志文件位置:
{MEMORY_DATA_DIR}/logs/hy_memory_{date}.log
默认: ~/.hy_memory/logs/hy_memory_{date}.log
"""
import contextvars
import logging
import os
import sys
from logging.handlers import TimedRotatingFileHandler
from pathlib import Path
from typing import Optional
# ================================================================
# request_id 上下文变量 (协程安全)
# ================================================================
_request_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
"request_id", default="-"
)
def set_request_id(request_id: str) -> None:
"""设置当前协程/线程的 request_id"""
_request_id_var.set(request_id)
def get_request_id() -> str:
"""获取当前协程/线程的 request_id"""
return _request_id_var.get()
class request_id_scope:
"""
临时把 request_id 设为指定值(默认哨兵 "-"),退出时恢复原值。
用于「进程级 / 初始化」日志:即便外层(如 App 请求上下文)已 set 了业务
request_id,初始化期间的日志也不应继承它,否则按 request_id 过滤会混入
一次性 init 噪音。
用法:
with request_id_scope(): # 默认 "-"
... 初始化、打 init 日志 ...
"""
def __init__(self, request_id: str = "-"):
self._rid = request_id
self._token = None
def __enter__(self):
self._token = _request_id_var.set(self._rid)
return self
def __exit__(self, exc_type, exc, tb):
if self._token is not None:
_request_id_var.reset(self._token)
return False
# ================================================================
# 自定义 Filter: 将 request_id 注入 LogRecord
# ================================================================
class RequestIdFilter(logging.Filter):
"""
从 contextvars 读取 request_id 并注入 LogRecord。
这样所有 handler 的 formatter 都可以用 %(request_id)s。
"""
def filter(self, record: logging.LogRecord) -> bool:
record.request_id = _request_id_var.get() # type: ignore[attr-defined]
return True
class _StdoutLevelFilter(logging.Filter):
"""
stdout handler 专用:只放 DEBUG/INFO 通过,WARNING 及以上拒绝。
配合独立的 stderr handler(setLevel=WARNING)实现 Unix 惯例的
双流分离,避免 INFO 日志被监控系统(如 OpenClaw)按 stderr=WARN 误标。
"""
def filter(self, record: logging.LogRecord) -> bool:
return record.levelno < logging.WARNING
# ================================================================
# 日志配置
# ================================================================
_LOG_FORMAT = (
"%(asctime)s [%(levelname)s] [%(request_id)s] %(name)s: %(message)s"
)
_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
# 全局标记,避免重复配置
_logging_configured = False
class SingleLineFormatter(logging.Formatter):
"""
纯文本 formatter,但保证每条日志输出为单行。
问题:message / exception 里可能含真实换行符(如用户 query 带 \\n),
单行模板被换行符截断后,下游按行采集的平台会拿到半截记录并报解析错误。
解决:渲染完成后把 \\r\\n 等控制换行转义为字面 \\n / \\r。
"""
def format(self, record: logging.LogRecord) -> str:
s = super().format(record)
if "\n" in s or "\r" in s:
s = s.replace("\\", "\\\\").replace("\r", "\\r").replace("\n", "\\n")
return s
class JsonLineFormatter(logging.Formatter):
"""
结构化 JSON Lines formatter(每条日志一行合法 JSON)。
供按 JSON 解析每一行的日志采集平台使用:message 里的换行会被 json
自然转义,不会截断,也不会出现 "[json] error field" 之类的解析报错。
字段:ts / level / request_id / logger / msg(+ exc 异常栈,如有)。
"""
def format(self, record: logging.LogRecord) -> str:
import json
payload = {
"ts": self.formatTime(record, _DATE_FORMAT),
"level": record.levelname,
"request_id": getattr(record, "request_id", "-"),
"logger": record.name,
"msg": record.getMessage(),
}
if record.exc_info:
payload["exc"] = self.formatException(record.exc_info)
return json.dumps(payload, ensure_ascii=False, default=str)
def _make_formatter() -> logging.Formatter:
"""
根据 MEMORY_LOG_FORMAT 选择 formatter:
- "json" → JsonLineFormatter(结构化,供 JSON 采集平台)
- 其它/未设置(默认) → SingleLineFormatter(纯文本,但保证单行不被换行截断)
"""
fmt = os.getenv("MEMORY_LOG_FORMAT", "text").strip().lower()
if fmt == "json":
return JsonLineFormatter()
return SingleLineFormatter(_LOG_FORMAT, datefmt=_DATE_FORMAT)
def _default_log_dir() -> str:
"""
确定日志目录:
1. 环境变量 MEMORY_LOG_DIR
2. {MEMORY_DATA_DIR}/logs/
3. ~/.hy_memory/logs/
"""
explicit = os.getenv("MEMORY_LOG_DIR")
if explicit:
return explicit
data_dir = os.getenv(
"MEMORY_DATA_DIR",
os.path.join(str(Path.home()), ".hy_memory"),
)
return os.path.join(data_dir, "logs")
def setup_logging(
log_dir: Optional[str] = None,
retention_days: int = 15,
level: Optional[int] = None,
) -> None:
"""
配置 hy_memory 模块的日志。
- 文件输出: TimedRotatingFileHandler, 每天午夜滚动, 保留 retention_days 天
- 控制台输出: 双流分离 — DEBUG/INFO 走 stdout,WARNING/ERROR/CRITICAL 走 stderr
(遵循 Unix 惯例;OpenClaw 等监控平台会把 stderr 整体标 WARN,
INFO 走 stdout 才不会被误归为告警)
- 所有日志行包含 request_id 字段
Args:
log_dir: 日志目录。默认 {MEMORY_DATA_DIR}/logs/
retention_days: 日志保留天数,默认 15
level: 日志级别。默认从环境变量 MEMORY_LOG_LEVEL 读取,缺省 INFO
可多次调用,但只有首次生效。
"""
global _logging_configured
if _logging_configured:
return
_logging_configured = True
if level is None:
level = getattr(logging, os.getenv("MEMORY_LOG_LEVEL", "INFO").upper(), logging.INFO)
# 确定日志目录并创建
resolved_dir = log_dir or _default_log_dir()
os.makedirs(resolved_dir, exist_ok=True)
# hy_memory 根 logger
root_logger = logging.getLogger("hy_memory")
root_logger.setLevel(level)
# request_id filter — 必须加在 handler 上而非 logger 上。
# 原因: Python logging propagation 机制中,子 logger (如 hy_memory.client)
# 的日志记录传播到父 logger 时,只调用父 logger 的 handlers,
# 不经过父 logger 的 filters。如果 filter 只在 logger 上,
# 子 logger 的记录到达 handler 时 record 上没有 request_id,
# formatter 就会 KeyError crash。
req_filter = RequestIdFilter()
formatter = _make_formatter()
# ---- 文件 Handler ----
log_file = os.path.join(resolved_dir, "hy_memory.log")
file_handler = TimedRotatingFileHandler(
filename=log_file,
when="midnight",
interval=1,
backupCount=retention_days,
encoding="utf-8",
)
# 滚动后文件名: hy_memory.log.2026-03-21
file_handler.suffix = "%Y-%m-%d"
file_handler.setFormatter(formatter)
file_handler.setLevel(level)
file_handler.addFilter(req_filter)
root_logger.addHandler(file_handler)
# ---- 控制台 Handler: 双流分离 ----
# stdout: DEBUG / INFO(用 filter 排除 WARNING 及以上)
# stderr: WARNING / ERROR / CRITICAL
# 修复 Issue: 之前所有级别都走单 StreamHandler 默认 stderr,
# OpenClaw 等监控平台会把整个 stderr 标 WARN,导致 INFO 日志
# 被误标为告警,刷屏。
stdout_handler = logging.StreamHandler(sys.stdout)
stdout_handler.setFormatter(formatter)
stdout_handler.setLevel(level)
stdout_handler.addFilter(req_filter)
stdout_handler.addFilter(_StdoutLevelFilter())
root_logger.addHandler(stdout_handler)
stderr_handler = logging.StreamHandler(sys.stderr)
stderr_handler.setFormatter(formatter)
# stderr 永远只接 WARNING+,独立于全局 level(即使全局 level=DEBUG,
# stderr 也不会拿到 INFO/DEBUG 行)
stderr_handler.setLevel(logging.WARNING)
stderr_handler.addFilter(req_filter)
root_logger.addHandler(stderr_handler)
# 避免日志向上传播到 root logger 导致重复输出
root_logger.propagate = False
# Suppress noisy third-party debug logs
for noisy in ("openai", "httpx", "httpcore", "urllib3"):
logging.getLogger(noisy).setLevel(logging.WARNING)
root_logger.debug(
f"Logging configured: dir={resolved_dir} "
f"retention={retention_days}d level={logging.getLevelName(level)}"
)