Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(logger): namespace log format configuration and isolate log tests (#4639)
lyingbug15d1dd0590f8
diff --git a/.env.example b/.env.exampleindex 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=truediff --git a/.github/workflows/app.yml b/.github/workflows/app.ymlindex 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.ymlindex 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.tsindex 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.goindex 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.goindex 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(tinterfaces.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.+ <-releaseReadreturn 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(tdone := 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(tt.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.goindex 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.goindex 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.goindex 37fa88851..10edf8da8 100644--- a/internal/logger/logger_test.go+++ b/internal/logger/logger_test.go@@ -2,6 +2,8 @@ package loggerimport ("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.shindex 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.shindex 24bb5418c..95e6049ab 100644--- a/scripts/test-git-hooks.sh+++ b/scripts/test-git-hooks.sh@@ -8,7 +8,8 @@ trap 'rm -rf "$fixture"' EXITmkdir -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 bashset -euo pipefail@@ -19,7 +20,7 @@ case "$1" inprintf '%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 ) ]]; thenecho "App tests inherited the developer log template" >&2exit 1fidiff --git a/website-docs/01-getting-started/04-configuration.md b/website-docs/01-getting-started/04-configuration.mdindex 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.mdindex 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.mdindex 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/资源索引。