企业官网建设流程全解析

Loki API一次讲透：5分钟跑通日志聚合接口

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

Loki是类Prometheus的日志聚合系统，Loki API是它的数据入口：POST推日志，GET用LogQL查日志，标签当索引。我们从跑通第一个请求讲起，最后给一份生产踩坑清单，全部复制即跑。

🔍 跑通第一个请求

先别急着写数据，用一个最轻的读端点确认Loki活着：

curl http://localhost:3100/loki/api/v1/labels

返回{"status":"success","data":[]}就算通了。空数组很正常——还没人写过日志。这一步能排除 90% 的"我是不是配错了"问题。

写入与查询：两个核心场景

日志聚合只有两个本质动作：写进去，查出来。对应Loki的两个REST接口：POST /loki/api/v1/push和GET /loki/api/v1/query（query_range）。

推送日志：streams三层结构

push请求体只有一层嵌套要记：streams是数组，每个流由stream（标签集合，决定日志归到哪条流）和values（[纳秒时间戳, 日志内容]的数组）组成。同标签的日志天然同流：

curl -X POST http://localhost:3100/loki/api/v1/push \ -H "Content-Type: application/json" \ -d '{"streams":[{"stream":{"job":"demo","host":"server-01"},' '"values":[["'$(date +%s%N)'","Hello Loki, first log"]]}]}'

等个一两秒（ingester默认按周期刷盘），再发一次第一条命令的labels，就能看到data里出现job和host。

LogQL查询：即时与范围各一条

查询端点都接收 LogQL 表达式（URL编码后）。标签选择器{job="demo" |= "Hello"}的意思是：从 job 为 demo 的流里过滤含 Hello 的行。

# 即时查询：只看某个时刻，limit 控制条数 curl "http://localhost:3100/loki/api/v1/query?query={job=%22demo%22}&limit=10&time=$(date +%s)"

# 范围查询：start/end 为Unix秒，step 是聚合步长 curl "http://localhost:3100/loki/api/v1/query_range?query={job=%22demo%22}%20%7C%3D%20%22Hello%22&start=$(date -d '1 hour ago' +%s)&end=$(date +%s)&step=1m"

两者的响应结构一致：data.result是个数组，日志查询里每项含stream（标签）和values（时间戳+内容）；换成sum(count_over_time(...))这类聚合器，返回的则是matrix（时间点+数值）。想系统学语法，看 LogQL文档。

标签：Loki的"索引灵魂"

Loki不解析日志正文，只给标签建索引——所以你能多快查到一条日志，取决于标签设计得多好。两个元数据端点是探索数据的起点：

curl http://localhost:3100/loki/api/v1/label/job/values

上图解释了为什么标签是灵魂：相同的标签组合会哈希出同一个流ID，日志聚进同一组chunk；标签任何一个值变了，就是另一条流、另一份索引。高基数标签（比如把user_id塞进标签）会制造海量流，存储和查询一起崩。

⚠️ 踩坑与调优清单

1. 400 先看编码：Content-Encoding: gzip但发了明文，或JSON里时间戳少了引号，是最常见的400。values里的时间戳必须是字符串。
2. 429 被限流不是故障：ingester按租户限流，批量写入时把每批控制在 1MB 内，别攒大包硬怼。
3. 500 先看ingester：写链路问题 9 成在 ingester 侧，查它的日志和内存，而不是反复重试。
4. 标签别超过10个：高基数标签会拖垮查询，instance可以用，request_id这种别进标签——把它留在日志正文里，用|=过滤。
5. 查询加| limit或限定时间窗：query_range不设start/end或step太小，会把整个索引扫到冒烟。
6. 时间戳用纳秒：$(date +%s%N)，差三个零就是25年后。

下一步

把 Loki HTTP API参考 留作速查手册——tail、series、index/volume这些端点都能覆盖日常运维。真正的闭环在 Grafana：接入上面的Loki数据源，LogQL查询会从curl搬进查询框，配合时间选择器完成可视化；写入侧则把 Promtail 指向同一个 push 端点。跑通本文两条curl的那一刻，你的日志管道其实已经活了。

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki