Beego日志必须转为JSON结构化输出才能对接Loki，需用zerolog/zap替换默认日志器或手动包装LevelWriter，关键字段包括level、service、trace_id、ts，Promtail配置须匹配路径与行首格式，并确保每行是独立合法JSON。
Beego 默认日志输出是纯文本、无结构、无标签的，直接对接 Loki 会查不到任何有效字段，log_level、service、trace_id 全部丢失——这不是配置问题，是日志格式根本没对齐。
Beego 日志必须转成 JSON 结构化输出
Beego 自带 logs 包不支持原生 JSON 序列化，SetLogger("file", ...) 写出的仍是 key=value 拼接格式，Loki 的 Promtail 或 Fluent Bit 无法提取标签。必须绕过默认日志引擎，用结构化日志库接管。
- 推荐用
zerolog或zap替换 Beego 的logs：在main.go初始化阶段禁用beego.BeeLogger，改用zerolog.New(os.Stdout).With().Timestamp().Logger() - 若坚持用 Beego 日志，需手动包装：重写
logs.LevelWriter接口，在Write方法里把msg和level封装成 map，再json.Marshal写入文件 - 关键字段不能少：
level（映射为 Loki 的level标签）、service（固定值如"user-api"）、trace_id（从 HTTP Header 或 context 提取）、ts（ISO8601 时间戳） - 避免使用
fmt.Sprintf拼接日志内容——它破坏 JSON 结构；所有对象必须用@前缀（如logger.Info().Str("user_id", uid).Msg("login success")）
Promtail 配置要匹配 Beego 日志路径与行首格式
Promtail 不会自动识别 Beego 的默认日志轮转名（如 beego.log.2026-08-21.001），且默认按行首时间戳解析，而 Beego 文本日志的日期在行中（[INFO] [2026/08/21 12:05:01]），会导致 __line__ 解析失败、timestamp 字段为空。
- 确保 Beego 日志写入固定路径，例如
/var/log/beego/app.json，并在 Promtailscrape_configs中显式指定：static_configs: - targets: ['localhost'] labels: job: beego __path__: /var/log/beego/app.json - 若用文本日志过渡，必须配
pipeline_stages提取字段：match: '{job="beego"} | json | line_format "{{.level}} {{.msg}}" | pattern "(?P<level>\w+) (?P<msg>.*)"</msg></level> - Linux 容器中注意权限：Beego 进程 UID 必须对
/var/log/beego/有写权限，Promtail 进程 UID 必须有读权限，否则静默跳过文件 -
auto_kubernetes_labels: true可以自动注入namespace、pod_name，但前提是 Promtail 运行在 Kubernetes 中且 ServiceAccount 有对应 RBAC
Loki 查询时必须用标签过滤，不能依赖全文搜索
Loki 不索引日志内容，只索引标签（job、level、service 等）。如果你在 Grafana 中输入 {job="beego"} |= "timeout" 却查不到结果，大概率是 timeout 字符串不在日志行内，或该行没被正确打上 job 标签。
- 先验证标签是否生效：执行
{job="beego"}，看是否返回任意日志流；若无结果，说明 Promtail 没采集成功或标签名不一致 - Beego 日志中的
level字段值（如"info"）要和 Loki 查询里的level="info"大小写一致；建议统一用小写，避免LevelInfovsinfo不匹配 - 查询含特殊字符的日志内容（如 URL、JSON 片段）要加双引号：
{service="order-api"} |= "GET /v1/orders?id=123"，否则会被解析为多个条件 - 跨服务串联靠
trace_id：确保 Beego 中间件已将X-Trace-ID注入日志字段，并在 Promtail 的labels配置中显式声明：labels: trace_id: "{{.trace_id}}"
Beego 中间件注入 trace_id 是串联日志的前提
没有 trace_id，你在 Grafana 里看到的只是孤立日志行。Beego 本身不提供分布式追踪集成，必须手动在请求生命周期中提取并透传。
- 在
controllers/base.go的Prepare方法中读取this.Ctx.Input.Header("X-Trace-ID")，若为空则生成 UUID v4 并设回响应头 - 用
context.WithValue把trace_id注入this.Ctx.Request.Context()，后续 handler 和日志调用都从 context 取值 - 日志记录时必须显式带上：
logger.Info().Str("trace_id", tid).Str("path", this.Ctx.Input.URL()).Msg("request start") - 别用 Beego 的
beego.Info()直接打日志——它拿不到 context，trace_id会丢失
最容易被忽略的是日志编码和换行：Beego 写 JSON 到文件时若用了 os.O_APPEND | os.O_CREATE 但没强制每条日志后加
，Promtail 会把多条日志当成一行，导致 JSON 解析失败、字段全丢。结构化日志不是“能输出就行”，而是每一行必须是合法、独立、可解析的 JSON 对象。
