Go 程序怎么把日志发给 Loki？别走 HTTP 轮子，用 promtail 旁路采集
Go 应用直接连 Loki 的 HTTP API 写日志，看似简单，实则埋雷：连接复用难、批次控制弱、失败重试逻辑自己写、还容易拖慢主流程。Loki 官方推荐的路径是「应用只输出结构化日志到 stdout/stderr，由 promtail 在旁路采集、打标、转发」。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Go 程序用
log/slog或zerolog输出 JSON 格式日志到os.Stdout，确保每行一个 JSON 对象（避免多行堆栈混在单行里） -
promtail配置中用docker或journal类型发现日志源，而非file直读容器内文件（K8s 下/var/log/pods/...路径权限和生命周期不可靠） - 关键配置项：
pipeline_stages里加json解析阶段，否则 Loki 收到的是原始字符串，level、trace_id这些字段无法被查询 - 常见错误现象：
parse error: invalid character—— 多半是 Go 日志用了slog.WithGroup导致嵌套 JSON，或fmt.Printf混入非 JSON 行；用jq -R 'fromjson?'流式校验日志流能快速定位
Fluentd 和 Go 应用共存时，为什么日志字段总丢？重点查 fluent-plugin-parser 的 key_name
Fluentd 常被选作中间层，把 Go 日志统一转成 Loki 兼容格式。但很多团队发现 level 字段进不了 Loki，或者 msg 变成空字符串——问题不在 Go 输出，而在 Fluentd 的解析配置没对齐。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Go 输出 JSON 时，字段名用小写+下划线风格（如
log_level），避免大驼峰（LogLevel），因为fluent-plugin-parser默认不自动转换 key 名大小写 -
parser插件必须显式指定key_name log（如果 JSON 日志整体包在一个log字段里），或设reserve_data true保留原始字段，否则解析后只剩message - 性能影响：开启
suppress_parse_error_log true会掩盖格式错误，导致部分日志静默丢失；建议先关掉它，用fluentd --dry-run验证解析逻辑 - 使用场景差异：如果 Go 日志已含
timestamp字段，time_key必须设为该字段名，并配time_format %Y-%m-%dT%H:%M:%S%.9NZ，否则 Loki 时间戳会变成接收时间而非事件发生时间
Go 服务重启后 Loki 查不到旧日志？确认 promtail 的 positions 文件位置和权限
promtail 依赖 positions 文件记录每个日志文件读到哪一行，否则重启后从头重发，或跳过中间段。但在容器环境里，这个文件很容易落错地方、被清空、或因挂载权限失败而写不进去。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
positions文件路径必须挂载为持久卷（如 K8semptyDir不够用），且目录权限需为644、属主为 promtail 进程 UID（常被忽略：Alpine 镜像默认 UID=1001，而挂载的 hostPath 目录可能属 root） - 常见错误现象：
failed to read positions file: open /run/promtail/positions.yaml: permission denied—— 此时 promtail 会退回到内存记录位置，Pod 重启即丢失偏移 - 参数差异：
watcher_mode inotify在容器里不一定生效（尤其 Docker for Mac / Windows），可临时切回poll模式验证是否是 inotify 限制导致漏日志 - 兼容性注意：K8s 1.22+ 默认禁用
hostPath的type: DirectoryOrCreate权限提升，需在 PodSecurityPolicy 或 PodSecurityContext 中显式放开fsGroup
本地开发调试时，如何绕过 Kubernetes 快速验证日志链路？用 loki-canary + promtail -config.file
等部署完 K8s 才看日志是否通，周期太长。本地用最小闭环验证，比改 Helm Chart 更快定位是 Go 输出问题、还是采集配置问题。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 起一个单节点 Loki：
docker run -d -p 3100:3100 --name loki grafana/loki:2.9.2，无需配置，开箱即用 - Go 程序启动时加
LOG_LEVEL=debug并输出到./app.log；然后手动跑 promtail：promtail -config.file=promtail-local.yaml，其中positions设为./positions.yaml，clients指向http://localhost:3100/loki/api/v1/push - 关键检查点：运行
curl -s 'http://localhost:3100/loki/api/v1/label' | jq，有返回说明 Loki 收到了数据；再查curl -s 'http://localhost:3100/loki/api/v1/query?query={job="my-app"}' | jq，能看到日志行才算全链路通 - 容易踩的坑：本地 macOS 上 Docker 的
localhost对容器不可见，clients.url得写成http://host.docker.internal:3100/...
字段映射、时间解析、positions 持久化这三处，任何一个没对齐，日志就断在半路。线上出问题时，优先抓 promtail 的日志，而不是翻 Go 应用的 stdout。
