Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(logger): namespace log format configuration and isolate log tests (#4639)

lyingbug15d1dd0590f8
diff --git a/.env.example b/.env.example
index 8032fcab7..b31f190a1 100644
--- a/.env.example
+++ b/.env.example
@@ -57,8 +57,9 @@ GIN_MODE=release
# LOG_LEVEL=debug
# 日志文件路径(留空只输出 stdout);LLM_DEBUG_LOG 开启时同目录写 llm_debug.log。
# LOG_PATH=
-# 自定义日志格式模板(留空用内置默认格式)。
-# LOG_FORMAT=
+# 自定义日志格式模板,必须包含 %msg(留空用内置默认格式;不支持 json 关键字)。
+# 未设置时兼容旧 LOG_FORMAT;显式设置为空可禁用旧变量。
+# WEKNORA_LOG_FORMAT=
# LLM 调试日志:把每次大模型调用的完整请求/响应写入独立文件,排查上下文问题用。
# 可选值:true(写 LOG_PATH 同目录 llm_debug.log)/ false/空(关闭)/ 指定文件路径。
# LLM_DEBUG_LOG=true
diff --git a/.github/workflows/app.yml b/.github/workflows/app.yml
index 0691876ae..c93390392 100644
--- a/.github/workflows/app.yml
+++ b/.github/workflows/app.yml
@@ -78,7 +78,7 @@ env:
GO_VERSION: "1.26"
GOPROXY: https://proxy.golang.org,direct
# Keep tests independent of a developer machine's custom log template.
- LOG_FORMAT: ""
+ WEKNORA_LOG_FORMAT: ""
BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
jobs:
diff --git a/docker-compose.yml b/docker-compose.yml
index 03ff49c04..b4ccc7f0e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -83,8 +83,8 @@ services:
- LOG_LEVEL=${LOG_LEVEL:-debug}
# 日志文件路径(留空则只输出 stdout);LLM_DEBUG_LOG 开启时同目录写 llm_debug.log
- LOG_PATH=${LOG_PATH:-}
- # 自定义日志格式模板(留空用内置默认格式)
- - LOG_FORMAT=${LOG_FORMAT:-}
+ # 自定义日志格式模板,必须包含 %msg;显式留空用默认格式,未设置时兼容旧变量
+ - WEKNORA_LOG_FORMAT=${WEKNORA_LOG_FORMAT-${LOG_FORMAT:-}}
# LLM 调试日志:true 写 LOG_PATH 同目录 llm_debug.log,或指定路径;留空关闭
- LLM_DEBUG_LOG=${LLM_DEBUG_LOG:-false}
# ========== 运行时基础 ==========
diff --git a/frontend/src/views/knowledge/settings/chunkingSamples.ts b/frontend/src/views/knowledge/settings/chunkingSamples.ts
index 6241a8faf..7f638b2f2 100644
--- a/frontend/src/views/knowledge/settings/chunkingSamples.ts
+++ b/frontend/src/views/knowledge/settings/chunkingSamples.ts
@@ -147,8 +147,8 @@ docker pull docker.m.daocloud.io/wechatopenai/weknora-ui:v0.5.0
### Q8: 如何启用多模态?
在知识库的"多模态配置"中开启,并选择一个 VLM 模型(如 GPT-4o、Qwen2.5-VL)。开启后,文档中的图片会被 VLM 描述并参与检索。
-### Q9: 怎么把日志改成 JSON 格式?
-设置 \`LOG_FORMAT=json LOG_LEVEL=info\`,便于接入 ELK / Loki 等日志栈。
+### Q9: 如何自定义日志格式?
+设置 \`WEKNORA_LOG_FORMAT="%d %level %msg" LOG_LEVEL=info\`。模板必须包含 \`%msg\`;留空使用默认格式,\`json\` 不是受支持的格式关键字。
## 检索与召回
diff --git a/internal/application/service/knowledgebase_search_partial_test.go b/internal/application/service/knowledgebase_search_partial_test.go
index 63b5b7610..6ebc8c485 100644
--- a/internal/application/service/knowledgebase_search_partial_test.go
+++ b/internal/application/service/knowledgebase_search_partial_test.go
@@ -4,25 +4,26 @@ import (
"bytes"
"context"
stderrors "errors"
- "os"
"testing"
"github.com/Tencent/WeKnora/internal/application/service/retriever"
- "github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
+ "github.com/sirupsen/logrus"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
-// captureServiceLogs redirects the process logger for one test, so the WARN
-// raised for a partial retrieve can be asserted on. Not parallel-safe: the
-// logger output is process-wide.
-func captureServiceLogs(t *testing.T) *bytes.Buffer {
+// captureServiceLogs supplies a request-scoped logger with a known format and
+// level, independent of host configuration and without changing the global logger.
+func captureServiceLogs(t *testing.T) (context.Context, *bytes.Buffer) {
t.Helper()
var buf bytes.Buffer
- logger.SetOutput(&buf)
- t.Cleanup(func() { logger.SetOutput(os.Stdout) })
- return &buf
+ log := logrus.New()
+ log.SetOutput(&buf)
+ log.SetFormatter(&logrus.TextFormatter{DisableColors: true, DisableTimestamp: true})
+ log.SetLevel(logrus.WarnLevel)
+ ctx := context.WithValue(context.Background(), types.LoggerContextKey, logrus.NewEntry(log))
+ return ctx, &buf
}
func keywordsRetrieveParams(query string) []types.RetrieveParams {
@@ -39,7 +40,7 @@ func keywordsRetrieveParams(query string) []types.RetrieveParams {
// travels with the results (RetrieveResult.Error -> CompositeRetrieveEngine)
// and is logged here, without discarding what was retrieved (#3835).
func TestRetrieveFromStores_LogsPartialFailureAndKeepsResults(t *testing.T) {
- logs := captureServiceLogs(t)
+ ctx, logs := captureServiceLogs(t)
cause := stderrors.New("qdrant keyword search failed in 1 of 2 matched collections")
fake := &fakeRetrieveEngineService{
engineType: types.QdrantRetrieverEngineType,
@@ -56,7 +57,7 @@ func TestRetrieveFromStores_LogsPartialFailureAndKeepsResults(t *testing.T) {
}
res, err := (&knowledgeBaseService{}).retrieveFromStores(
- context.Background(), []*storeGroup{g}, retriever.EngineAwareNormalizer{})
+ ctx, []*storeGroup{g}, retriever.EngineAwareNormalizer{})
require.NoError(t, err, "a partial failure must not fail the search")
require.Len(t, res, 1)
@@ -70,7 +71,7 @@ func TestRetrieveFromStores_LogsPartialFailureAndKeepsResults(t *testing.T) {
// The multi-store path must keep partial results too, instead of cancelling
// siblings and failing the whole search.
func TestRetrieveFromStores_MultiGroupKeepsPartialResults(t *testing.T) {
- logs := captureServiceLogs(t)
+ ctx, logs := captureServiceLogs(t)
cause := stderrors.New("milvus keyword search failed in 2 of 3 matched collections")
partial := &fakeRetrieveEngineService{
engineType: types.MilvusRetrieverEngineType,
@@ -101,7 +102,7 @@ func TestRetrieveFromStores_MultiGroupKeepsPartialResults(t *testing.T) {
}
res, err := (&knowledgeBaseService{}).retrieveFromStores(
- context.Background(), groups, retriever.EngineAwareNormalizer{})
+ ctx, groups, retriever.EngineAwareNormalizer{})
require.NoError(t, err, "one degraded store must not fail the whole search")
require.Len(t, res, 2)
@@ -112,7 +113,7 @@ func TestRetrieveFromStores_MultiGroupKeepsPartialResults(t *testing.T) {
// A complete search that legitimately hit nothing must stay quiet: no partial
// warning, nil error.
func TestRetrieveFromStores_CompleteEmptySearchStaysQuiet(t *testing.T) {
- logs := captureServiceLogs(t)
+ ctx, logs := captureServiceLogs(t)
fake := &fakeRetrieveEngineService{
engineType: types.QdrantRetrieverEngineType,
support: []types.RetrieverType{types.KeywordsRetrieverType},
@@ -126,7 +127,7 @@ func TestRetrieveFromStores_CompleteEmptySearchStaysQuiet(t *testing.T) {
}
res, err := (&knowledgeBaseService{}).retrieveFromStores(
- context.Background(), []*storeGroup{g}, retriever.EngineAwareNormalizer{})
+ ctx, []*storeGroup{g}, retriever.EngineAwareNormalizer{})
require.NoError(t, err)
require.Len(t, res, 1)
@@ -138,7 +139,7 @@ func TestRetrieveFromStores_CompleteEmptySearchStaysQuiet(t *testing.T) {
// An engine-level failure still fails the search: exposing partial results must
// not weaken the all-or-nothing policy for stores that did not answer at all.
func TestRetrieveFromStores_EngineLevelErrorStillFails(t *testing.T) {
- logs := captureServiceLogs(t)
+ ctx, logs := captureServiceLogs(t)
cause := stderrors.New("vector store unavailable")
fake := &fakeRetrieveEngineService{
engineType: types.QdrantRetrieverEngineType,
@@ -155,7 +156,7 @@ func TestRetrieveFromStores_EngineLevelErrorStillFails(t *testing.T) {
}
res, err := (&knowledgeBaseService{}).retrieveFromStores(
- context.Background(), []*storeGroup{g}, retriever.EngineAwareNormalizer{})
+ ctx, []*storeGroup{g}, retriever.EngineAwareNormalizer{})
require.ErrorIs(t, err, cause)
assert.Nil(t, res, "an engine-level failure still returns no results")
diff --git a/internal/application/service/shell_job_followup_test.go b/internal/application/service/shell_job_followup_test.go
index fea869b8a..4fdcbf031 100644
--- a/internal/application/service/shell_job_followup_test.go
+++ b/internal/application/service/shell_job_followup_test.go
@@ -28,10 +28,15 @@ func TestShellJobHeartbeatRefreshesProvidersWhileReadsAndAnotherProviderBlock(t
interfaces.BackgroundActivity{ID: id, Kind: "shell"}, time.Minute, 0))
}
refreshed := make(chan string, 100)
- svc.remoteRead = func(ctx context.Context, _ interfaces.SessionRef, _ []string, _ map[string]string) (
+ readStarted := make(chan struct{}, len(refs))
+ releaseRead := make(chan struct{})
+ svc.remoteRead = func(_ context.Context, _ interfaces.SessionRef, _ []string, _ map[string]string) (
[]sandbox.ShellJobSnapshot, map[string]error,
) {
- <-ctx.Done()
+ readStarted <- struct{}{}
+ // Maintenance reads detach from sweep cancellation. Release this fake
+ // explicitly, just as the real remote exec has its own bounded lifetime.
+ <-releaseRead
return nil, nil
}
providerBlocked := make(chan struct{})
@@ -50,6 +55,8 @@ func TestShellJobHeartbeatRefreshesProvidersWhileReadsAndAnotherProviderBlock(t
})
// A sweep cannot reach renewRunning while waiting for this session lock.
locked, release := make(chan struct{}), make(chan struct{})
+ var releaseOnce sync.Once
+ releaseLock := func() { releaseOnce.Do(func() { close(release) }) }
lockDone := make(chan error, 1)
go func() {
lockDone <- index.WithSessionLock(context.Background(), refs[0], func(context.Context) error {
@@ -63,7 +70,8 @@ func TestShellJobHeartbeatRefreshesProvidersWhileReadsAndAnotherProviderBlock(t
done := make(chan error, 1)
t.Cleanup(func() {
cancel()
- close(release)
+ close(releaseRead)
+ releaseLock()
require.NoError(t, <-lockDone)
select {
case <-done:
@@ -85,6 +93,25 @@ func TestShellJobHeartbeatRefreshesProvidersWhileReadsAndAnotherProviderBlock(t
t.Fatal("one slow provider starved another session's TTL refresh")
}
}
+ // The map of claimed sessions has no stable order. Ensure the sweep has
+ // reached a blocked read even when it selected the locked session first.
+ releaseLock()
+ select {
+ case <-readStarted:
+ case <-time.After(time.Second):
+ t.Fatal("sweep never entered remote read")
+ }
+ for len(refreshed) > 0 {
+ <-refreshed
+ }
+ for range 2 {
+ select {
+ case sid := <-refreshed:
+ require.Equal(t, refs[1].SessionID, sid)
+ case <-time.After(time.Second):
+ t.Fatal("blocked read starved another session's TTL refresh")
+ }
+ }
}
func TestShellJobSubmitHonorsCancellationWhileWaitingForSessionLock(t *testing.T) {
diff --git a/internal/datasource/connector/yuque/client_test.go b/internal/datasource/connector/yuque/client_test.go
index 8a78214c1..b535b79a3 100644
--- a/internal/datasource/connector/yuque/client_test.go
+++ b/internal/datasource/connector/yuque/client_test.go
@@ -117,9 +117,9 @@ func TestClient_Ping_403WrapsInvalidCredentials(t *testing.T) {
}
func TestClient_TokenNeverLoggedInFull(t *testing.T) {
- t.Setenv("LOG_FORMAT", "")
- logger.ConfigureFromEnv()
t.Cleanup(func() { logger.ConfigureFromEnv() })
+ t.Setenv("WEKNORA_LOG_FORMAT", "")
+ logger.ConfigureFromEnv()
// Redirect the project's internal logger to an in-memory buffer so we can
// assert the raw token never appears in log output. Using stdlib `log`
diff --git a/internal/logger/logger.go b/internal/logger/logger.go
index e7c9665ad..8c2990a4a 100644
--- a/internal/logger/logger.go
+++ b/internal/logger/logger.go
@@ -67,7 +67,7 @@ const (
type CustomFormatter struct {
ForceColor bool // 是否强制使用颜色,即使在非终端环境下
- Template string // 自定义日志格式模板,通过 LOG_FORMAT 环境变量配置,为空则使用内置默认格式
+ Template string // 自定义日志格式模板,通过 WEKNORA_LOG_FORMAT 环境变量配置,为空则使用内置默认格式
// 模板占位符:%d=时间 %level=级别 %thread=goroutine %logger=caller %traceId=请求ID %msg=消息+结构化字段
// threadNeeded 缓存模板是否引用了 %thread,避免每条日志都调用一次 runtime.Stack。
@@ -233,7 +233,7 @@ func init() {
}
// ConfigureFromEnv 重新从环境变量应用日志配置。
-// 这允许在 main() 中加载 .env 后,让 LOG_LEVEL / LOG_PATH 立即生效。
+// 这允许在 main() 中加载 .env 后,让 LOG_LEVEL / LOG_PATH / WEKNORA_LOG_FORMAT 立即生效。
func ConfigureFromEnv() {
loggerMu.Lock()
defer loggerMu.Unlock()
@@ -346,11 +346,30 @@ func resolveLogPathFromEnv() string {
return defaultMacAppLogPath()
}
-// resolveLogFormatFromEnv 从环境变量 LOG_FORMAT 读取自定义日志格式模板。
-// 为空则使用内置默认格式;非空则作为模板,支持占位符:
+// resolveLogFormatFromEnv prefers WEKNORA_LOG_FORMAT, including an explicitly
+// empty value, and falls back to the deprecated LOG_FORMAT only when unset.
+// Nonempty templates must include %msg so configuration cannot hide log bodies.
+// 支持占位符:
// %d=时间 %level=级别 %thread=goroutine %logger=caller %traceId=请求ID %msg=消息+结构化字段
func resolveLogFormatFromEnv() string {
- return strings.TrimSpace(os.Getenv("LOG_FORMAT"))
+ name := "WEKNORA_LOG_FORMAT"
+ raw, ok := os.LookupEnv(name)
+ if !ok {
+ name = "LOG_FORMAT"
+ raw = os.Getenv(name)
+ }
+ tmpl := strings.TrimSpace(raw)
+ if tmpl == "" {
+ return ""
+ }
+ if !strings.Contains(tmpl, "%msg") {
+ fmt.Fprintf(os.Stderr, "logger: %s must contain %%msg; using the default log format\n", name)
+ return ""
+ }
+ if name == "LOG_FORMAT" {
+ fmt.Fprintln(os.Stderr, "logger: LOG_FORMAT is deprecated; use WEKNORA_LOG_FORMAT instead")
+ }
+ return tmpl
}
func defaultMacAppLogPath() string {
diff --git a/internal/logger/logger_test.go b/internal/logger/logger_test.go
index 37fa88851..10edf8da8 100644
--- a/internal/logger/logger_test.go
+++ b/internal/logger/logger_test.go
@@ -2,6 +2,8 @@ package logger
import (
"context"
+ "io"
+ "os"
"strings"
"testing"
"time"
@@ -10,6 +12,93 @@ import (
"github.com/sirupsen/logrus"
)
+func TestResolveLogFormatFromEnv(t *testing.T) {
+ const preferred = "%level | %msg"
+ const legacy = "legacy: %msg"
+ cases := []struct {
+ name string
+ preferred string
+ setNew bool
+ legacy string
+ want string
+ warning string
+ }{
+ {name: "default"},
+ {name: "preferred", setNew: true, preferred: preferred, want: preferred},
+ {name: "preferred overrides legacy", setNew: true, preferred: preferred, legacy: legacy, want: preferred},
+ {
+ name: "preferred overrides inherited json", setNew: true,
+ preferred: preferred, legacy: "json", want: preferred,
+ },
+ {name: "empty disables legacy", setNew: true, legacy: legacy},
+ {name: "whitespace disables legacy", setNew: true, preferred: " \t ", legacy: "json"},
+ {name: "trim template", setNew: true, preferred: " " + preferred + "\n", want: preferred},
+ {
+ name: "legacy compatibility", legacy: legacy, want: legacy,
+ warning: "LOG_FORMAT is deprecated; use WEKNORA_LOG_FORMAT instead",
+ },
+ {name: "legacy json preserves messages", legacy: "json", warning: "LOG_FORMAT must contain %msg"},
+ {
+ name: "preferred json preserves messages", setNew: true, preferred: "json", legacy: legacy,
+ warning: "WEKNORA_LOG_FORMAT must contain %msg",
+ },
+ {
+ name: "metadata only preserves messages", setNew: true, preferred: "%d %level",
+ warning: "WEKNORA_LOG_FORMAT must contain %msg",
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Setenv("LOG_FORMAT", tc.legacy)
+ t.Setenv("WEKNORA_LOG_FORMAT", tc.preferred)
+ if !tc.setNew {
+ if err := os.Unsetenv("WEKNORA_LOG_FORMAT"); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ // Capture startup diagnostics independently of the configured logger.
+ r, w, err := os.Pipe()
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = r.Close() }()
+ defer func() { _ = w.Close() }()
+ originalStderr := os.Stderr
+ os.Stderr = w
+ defer func() { os.Stderr = originalStderr }()
+ got := resolveLogFormatFromEnv()
+ os.Stderr = originalStderr
+ if err := w.Close(); err != nil {
+ t.Fatal(err)
+ }
+ warning, err := io.ReadAll(r)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got != tc.want {
+ t.Fatalf("template = %q, want %q", got, tc.want)
+ }
+ if tc.warning == "" && len(warning) != 0 {
+ t.Errorf("unexpected warning: %s", warning)
+ } else if tc.warning != "" && !strings.Contains(string(warning), tc.warning) {
+ t.Errorf("warning = %q, want %q", warning, tc.warning)
+ }
+ formatter := &CustomFormatter{Template: got}
+ entry := newEntry(logrus.WarnLevel, "partial retrieve failure", logrus.Fields{"kb_count": 2})
+ out, err := formatter.Format(entry)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{"partial retrieve failure", "kb_count=2"} {
+ if !strings.Contains(string(out), want) {
+ t.Errorf("log output lost %q: %s", want, out)
+ }
+ }
+ })
+ }
+}
+
func newEntry(level logrus.Level, msg string, data logrus.Fields) *logrus.Entry {
e := logrus.NewEntry(logrus.New())
e.Time = time.Date(2026, 5, 21, 10, 20, 30, 123_000_000, time.UTC)
diff --git a/scripts/git-hooks/common.sh b/scripts/git-hooks/common.sh
index 50fc128b3..e5cac3ed9 100755
--- a/scripts/git-hooks/common.sh
+++ b/scripts/git-hooks/common.sh
@@ -182,7 +182,7 @@ run_go_test_packages() {
(
cd "$ROOT"
# Match app.yml: a developer's custom log template must not alter assertions.
- LOG_FORMAT="" go test -count=1 "${pkgs[@]}"
+ WEKNORA_LOG_FORMAT="" go test -count=1 "${pkgs[@]}"
)
log_ok "go test"
}
diff --git a/scripts/test-git-hooks.sh b/scripts/test-git-hooks.sh
index 24bb5418c..95e6049ab 100644
--- a/scripts/test-git-hooks.sh
+++ b/scripts/test-git-hooks.sh
@@ -8,7 +8,8 @@ trap 'rm -rf "$fixture"' EXIT
mkdir -p "$fixture/scripts/git-hooks" "$fixture/bin"
cp "$repo_root/scripts/git-hooks/common.sh" "$fixture/scripts/git-hooks/"
export HOOK_TEST_LOG="$fixture/go.log"
-export LOG_FORMAT="developer-custom-template"
+export LOG_FORMAT="legacy: %msg"
+export WEKNORA_LOG_FORMAT="developer: %msg"
cat > "$fixture/bin/go" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
@@ -19,7 +20,7 @@ case "$1" in
printf '%s\n' example/internal/agent/tools example/internal/application/service example/docreader/proto
;;
vet|test)
- if [[ "$1" == test && -n "${LOG_FORMAT:-}" ]]; then
+ if [[ "$1" == test && ( -n "${WEKNORA_LOG_FORMAT:-}" || "${WEKNORA_LOG_FORMAT+x}" != x ) ]]; then
echo "App tests inherited the developer log template" >&2
exit 1
fi
diff --git a/website-docs/01-getting-started/04-configuration.md b/website-docs/01-getting-started/04-configuration.md
index 40cab4b84..0a76356b0 100644
--- a/website-docs/01-getting-started/04-configuration.md
+++ b/website-docs/01-getting-started/04-configuration.md
@@ -140,7 +140,7 @@ flowchart LR
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `GIN_MODE` | release | `debug` 开发模式(启用 Swagger)/ `release` 生产 |
-| `LOG_LEVEL` / `LOG_PATH` / `LOG_FORMAT` | debug / 空 / 空 | 日志级别、文件路径(空则仅 stdout)、自定义格式 |
+| `LOG_LEVEL` / `LOG_PATH` / `WEKNORA_LOG_FORMAT` | debug / 空 / 空 | 日志级别、文件路径(空则仅 stdout)、自定义格式(非空须含 `%msg`;未设置时兼容旧 `LOG_FORMAT`,显式空值禁用回退;不支持 `json` 关键字) |
| `LLM_DEBUG_LOG` | false | true 时在 LOG_PATH 同目录写 `llm_debug.log` |
| `TZ` | Asia/Shanghai | 时区 |
| `DEFAULT_LOCALE` | 空 | 前端界面默认语言(frontend 容器读取):`zh-CN` / `en-US` / `ru-RU` / `ko-KR` / `ja-JP`,非法值忽略。仅影响未手动切换过语言的用户,优先级:用户已选语言 > 本变量 > `zh-CN`;改完重启 frontend 容器即可,无需重建镜像 |
diff --git a/website-docs/02-architecture/02-backend-design.md b/website-docs/02-architecture/02-backend-design.md
index ef91e181d..08c035ba9 100644
--- a/website-docs/02-architecture/02-backend-design.md
+++ b/website-docs/02-architecture/02-backend-design.md
@@ -338,7 +338,7 @@ type AppError struct {
## 日志体系(internal/logger) {#_8-日志体系-internal-logger}
-- 基于 **logrus**,私有 `appLogger` 单例 + 自定义 Formatter(彩色终端输出;`LOG_FORMAT` 可用 `%d` `%level` `%traceId` `%msg` 等占位符自定义模板;`LOG_PATH` 设置后经 lumberjack 轮转写文件并剥离 ANSI 颜色码);
+- 基于 **logrus**,私有 `appLogger` 单例 + 自定义 Formatter(彩色终端输出;`WEKNORA_LOG_FORMAT` 可用 `%d` `%level` `%traceId` `%msg` 等占位符自定义模板;`LOG_PATH` 设置后经 lumberjack 轮转写文件并剥离 ANSI 颜色码);
- **request_id 贯穿**:`middleware.RequestID` 写入 context → `logger.GetLogger(ctx)` 自动提取并注入 `request_id` 字段;常用出口为 `logger.Infof/Warnf/Errorf(ctx, format, ...)` 与 `ErrorWithFields`;
- **LLM 调试日志**(`llm_logger.go`):`LLM_DEBUG_LOG=true` 时启用,按 request_id 分文件记录每次 LLM 调用(`LLMCallRecord`:CallType Chat/Embedding/Rerank/VLM、模型、耗时、完整消息与工具调用、错误),7 天自动清理,用于排查提示词和上下文问题。
diff --git a/website-docs/03-features/16-observability.md b/website-docs/03-features/16-observability.md
index e17f7999a..c365b6660 100644
--- a/website-docs/03-features/16-observability.md
+++ b/website-docs/03-features/16-observability.md
@@ -54,7 +54,7 @@ r.GET("/health", func(c *gin.Context) {
- 底层为**私有** logrus 实例(`appLogger`,避免外部依赖改写全局 logrus 导致日志丢失),自定义 `CustomFormatter`。
- 默认单行格式:`LEVEL[时间戳] [request_id 字段...] caller | message`,caller 为 `文件:行[函数名]`(`addCaller`)。
-- 可通过 `LOG_FORMAT` 环境变量提供模板,占位符:`%d`=时间、`%level`=级别、`%thread`=goroutine ID(仅模板引用时才取,避免每条日志跑 `runtime.Stack`)、`%logger`=caller、`%traceId`=request_id、`%msg`=消息+结构化字段。单趟 `strings.NewReplacer` 替换避免二次替换问题。
+- 可通过 `WEKNORA_LOG_FORMAT` 环境变量提供模板,占位符:`%d`=时间、`%level`=级别、`%thread`=goroutine ID(仅模板引用时才取,避免每条日志跑 `runtime.Stack`)、`%logger`=caller、`%traceId`=request_id、`%msg`=消息+结构化字段。单趟 `strings.NewReplacer` 替换避免二次替换问题。非空模板必须包含 `%msg`,否则输出警告并使用默认格式;`json` 不是受支持的格式关键字。新变量未设置时兼容旧 `LOG_FORMAT`(提示弃用),显式设为空则使用默认格式并禁用旧变量回退。
- 级别由 `LOG_LEVEL` 控制(`debug`/`info`/`warn`/`error`/`fatal`,未设置或非法时**默认 debug**)。
- 颜色:stdout 是终端时启用 ANSI 颜色;非终端(Docker 采集)禁用;写文件时 `ansiStripWriter` 剥离 ANSI 序列保持纯文本。
- 结构化字段 API:`logger.WithField(ctx, k, v)` / `WithFields` 把带字段的 entry 存进 context(`types.LoggerContextKey`),后续 `logger.Infof(ctx, ...)` 自动携带;`WarnWithFields` 专用于审计相关事件(跨租户探测、不变量破坏),便于日志聚合器按 tenant/资源索引。