Loki官方client（如logproto）面向日志收集器而非业务服务，引入会拉入冗余依赖、启动gRPC server并强制WAL/batching，加重微服务负担；实际项目更推荐直接调用/loki/api/v1/push HTTP API，轻量可控。
为什么不用 Loki 官方 client 而要直接发 POST？
Loki 官方 lokilog client（如 github.com/grafana/loki/pkg/logproto）面向的是日志收集器（如 Promtail），不是业务服务直传场景。微服务里直接引入它会拉入大量依赖、启动 gRPC server、强制处理 WAL 和 batching，反而加重负担。真实项目里更常用的是用 HTTP API 直接推送，轻量可控。
关键点：
- Loki 的日志写入接口是
/loki/api/v1/push，只认 JSON 格式、要求Content-Type: application/json - 必须带
X-Scope-OrgID请求头（哪怕单租户也得填，常见填fake或服务名） - 每条日志必须带时间戳（
nanoseconds since Unix epoch），不能用字符串时间 - Labels 必须是扁平 key-value，且
job和instance是推荐但非强制的保留 label
怎么构造合法的 Loki 日志推送 payload？
Go 里最简方式是定义结构体 + json.Marshal，别手拼字符串。注意字段名大小写和嵌套层级 —— Loki API 对 JSON 结构很敏感，错一层就 400。
示例结构：
type LokiEntry struct {
Stream map[string]string `json:"stream"`
Values [][2]string `json:"values"`
}
<p>type LokiPushRequest struct {
Streams []LokiEntry <code>json:"streams"</code>
}
使用时：
-
Streammap 至少包含"job"（比如"auth-service"）、"instance"（比如"auth-7f8d9c4b5-xvq2r"） -
Values是[timestamp_ns, log_line]的二维数组；时间戳必须是字符串格式的纳秒整数，例如fmt.Sprintf("%d", time.Now().UnixNano()) - 一行日志一个
Values元素，不要攒批超过 10–20 条，否则可能触发 Loki 的max_line_length或max_chunk_age限制
HTTP 客户端要不要复用？超时怎么设？
必须复用 *http.Client，否则每个日志都建连接，几万 QPS 下直接打爆文件描述符。同时超时不能设太短 —— Loki 写入路径含压缩、索引、TSDB flush，高峰时延迟可能到 200–300ms。
建议配置：
-
Timeout: 5 * time.Second（比默认 30s 更合理，避免阻塞 goroutine） -
Transport.MaxIdleConns: 100，MaxIdleConnsPerHost: 100 - 禁用 HTTP/2（
ForceAttemptHTTP2: false）—— 某些 k8s 环境下 HTTP/2 连接复用不稳定，导致偶发 EOF - 加简单重试（最多 1 次），仅针对
502/503/504和网络错误；别重试400（说明 payload 错了）
怎么避免日志内容破坏 JSON 结构？
业务日志常含双引号、换行、控制字符，不转义就导致整个 POST body 解析失败，Loki 返回 400 Bad Request: invalid character。别信“日志都是 ASCII”这种假设。
正确做法：
- 用
json.Marshal序列化日志消息本身（不是整个 payload），它自动转义 - 别用
strings.ReplaceAll(logLine, " ", "\n")这类手动替换 —— 漏掉"、u2028等 Unicode 分隔符 - 如果日志已是一段 JSON（如 zap 的
JSONEncoder输出），先json.Unmarshal再json.Marshal二次封装，确保嵌套安全
最容易被忽略的是：Loki 不解析日志内容语义，但严格校验 JSON 语法。一个没闭合的双引号，会让整批日志丢弃，且无明确错误反馈 —— 查不到日志时，先 curl -v 抓包看响应体。
