Go应用应只向os.Stdout输出单行JSON日志，由Promtail或Fluent Bit采集，而非直连Loki；需统一字段命名、禁用换行、正确配置解析与标签映射，避免权限和静默丢弃问题。
Go 应用不该自己直连 Loki 发日志，除非你明确需要绕过采集层做特殊控制（比如调试、单点埋点、离线补录）。绝大多数生产场景下，硬编码 HTTP 调用 /loki/api/v1/push 只会带来连接泄漏、重试失当、批次混乱和主流程阻塞——Loki 官方文档也明确推荐「应用只输出结构化日志到 stdout/stderr，由 Promtail 或 Fluent Bit 旁路采集」。
Go 应用只往 os.Stdout 写 JSON 日志
这是整个链路最稳的起点。Kubernetes 的 docker logs 和 kubectl logs 默认就是读这个流；Promtail 默认监听 /var/log/pods/ 下的 symlink，Fluent Bit 默认读 /dev/stdout pipe，都不需要改配置就能接上。
- 用
slog（Go 1.21+）或zerolog，禁用 console 格式，强制 JSON 输出：slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
- 每条日志必须是单行 JSON，不能换行（否则 Promtail 解析失败，整条丢弃）
- 字段名统一小写+下划线，比如
log_level、request_id、trace_id；避免LogLevel这类驼峰，Fluentd 的parser插件默认不自动转换 key 名大小写 - 别写
/app/logs/app.log——容器重启即丢，挂载卷增加运维负担，多副本日志分散难聚合
Promtail 配置必须对齐 Go 日志结构
Promtail 不是“拿来就用”，它靠 scrape_configs 抓日志、靠 pipeline_stages 解析字段、靠 static_labels 补全局标签。错一个环节，level 就进不了 Loki，time 就变成接收时间而非事件时间。
- 如果 Go 日志里有
"ts":"2026-04-03T10:45:00.123456789Z"字段，Promtail 的pipeline_stages必须配timestampstage，且source设为ts，format设为RFC3339Nano -
static_labels至少包含job（如"golang-api"）和env（如"prod"），这些会成为 LogQL 查询的label -
positions文件路径必须挂载为持久卷（emptyDir不行），目录权限设为644，属主 UID 必须匹配 Promtail 进程 UID（Alpine 镜像常为1001，但 hostPath 目录可能属root，导致无法写入 positions，反复重推旧日志）
Fluent Bit / Fluentd 解析失败的典型表现
日志进了 Loki，但 level 是空、msg 是空、查询时 {job="golang-api"} |= "error" 没结果——大概率是解析阶段字段提取失败，而不是 Go 输出错了。
立即学习“go语言免费学习笔记（深入）”；
- Fluentd：检查
filter插件是否启用了suppress_parse_error_log true，这个开关一开，格式错误的日志就静默丢弃，查不到任何报错 - Fluent Bit：确认
Parser配置里的Key_Name和 Go 日志字段名完全一致（包括大小写），且Time_Key指向真实时间字段（不是time就是ts） - 验证方式：先关掉所有 suppress 开关，用
fluentd --dry-run或 Fluent Bit 的stdout输出插件，看解析后字段是否完整
Loki 查询时发现日志时间不准或标签缺失
LogQL 查询结果里时间戳全是日志被 Promtail 收到的时间，或者 {job="golang-api", level="error"} 查不到数据——说明标签没打进去，或时间字段没被正确识别。
- 用
/loki/api/v1/series?match=%7Bjob%3D%22golang-api%22%7D直接查 Loki 是否创建了对应 series；没创建，说明 Promtail 根本没把日志推过去，先查 Promtail 日志里的push error或dropped entry - 查到了 series 但时间不对：Promtail 的
timestampstage 没生效，或者 Go 日志里没带ts字段，导致 fallback 到接收时间 - 查到了 series 但
level标签为空：Fluent Bit/Fluentd 的 parser 提取失败，或 Promtail 的labelsstage 没把解析出的字段映射成标签（例如没写label: level）
最容易被忽略的不是代码怎么写，而是 Promtail 的 positions 权限、Fluentd 的 suppress_parse_error_log、以及 Go 日志里那个看似无害的换行符——它们不会报错，只会让日志在某个环节无声消失。
