编写 LogQL 查询、配置 Loki 日志管道…

在 Grafana Loki 中查询、聚合、告警、接入和排查日志管道时使用。

适用场景

解决思路

1. 使用 Loki 时只把元数据 labels 建索引，不索引完整日志内容；查询时用日志流选择器缩小范围，再做行过滤、解析和聚合。
2. 每个 LogQL 查询必须包含日志流选择器；支持 {app="nginx"} 精确匹配、{app!="nginx"} 不等于、{app=~"nginx|apache"} 正则匹配、{app!~"debug.*"} 正则不匹配、{app="nginx", env="prod"} 多标签 AND。
3. 把行过滤器作为 pipeline 第一阶段并尽量前置以提升性能；支持 {app="nginx"} |= "error" 包含、!= "info" 不包含、|~ "error|warn" 正则匹配、!~ "health.*check" 正则不匹配、|= `"status":5` 用反引号避免转义。
4. 用 JSON 解析器：{app="api"} | json；也可指定字段映射，如 | json status="http_status", path="request.path"。
5. 用 Logfmt 解析器：{app="api"} | logfmt；支持 --strict 和 --keep-empty。
6. 用 Pattern 解析器按位置提取，_ 丢弃字段，如 {app="nginx"} | pattern `<ip> - - <_> "<method> <uri> <_>" <status> <bytes>`。
7. 用 Regexp 解析器通过命名捕获组提取，如 {app="nginx"} | regexp `(?P<method>\w+) (?P<path>\S+) HTTP/(?P<version>\S+)`。
8. 用 Unpack 解析器解包 Promtail packed labels：{app="api"} | unpack。
9. 解析后使用标签过滤器：| status >= 500、| status == 200 and method != "OPTIONS"、| duration > 1s、| level =~ "error|warn"、| bytes > 20MB、| path != "/healthz"。
10. 用 line_format 重写日志行：{app="api"} | json | line_format "{{.method}} {{.path}} -> {{.status}} ({{.duration}})"；也可 {app="api"} | logfmt | line_format `{{.level | upper}}: {{.msg}}`。
11. 用 label_format 新建或重命名标签：| label_format new_name=old_name；批量如 severity=level, svc=app；模板如 msg=`{{.level}}: {{.message}}`。
12. 用 drop/keep 丢弃或保留标签/字段：| drop filename, level="debug"；| keep level, status, method。
13. 用 decolorize 去除 ANSI 颜色：{app="cli-tool"} | decolorize。
14. 计算每秒日志行数用 rate({app="nginx"}[5m])。
15. 计算窗口内总日志行数用 count_over_time({app="nginx"}[1h])。
16. 计算每秒字节数用 bytes_rate({app="nginx"}[5m])。
17. 计算总字节数用 bytes_over_time({app="nginx"}[1h])。
18. 在范围内无日志时返回 1 用于缺失告警，用 absent_over_time({app="nginx"}[5m])。
19. 按服务聚合错误率用 sum(rate({env="prod"} |= "error" [5m])) by (app)。
20. 取最活跃前 5 个服务用 topk(5, sum(rate({env="prod"}[5m])) by (app))。
21. 统计所有服务错误总数用 sum(count_over_time({env="prod"} |= "error" [5m]))。
22. 从日志提取数值做解包范围聚合：平均耗时用 avg_over_time({app="api"} | logfmt | unwrap duration [5m])。
23. 计算 95 分位延迟用 quantile_over_time(0.95, {app="api"} | logfmt | unwrap duration [5m]) by (app)。
24. 对 JSON 日志字节数求和用 sum_over_time({app="api"} | json | unwrap bytes [5m])。
25. 需要把 duration 字符串转换为秒时用 avg_over_time({app="api"} | logfmt | unwrap duration | duration_seconds [5m])。
26. 用 offset 比较当前与历史：rate({app="nginx"}[5m]) / rate({app="nginx"}[5m] offset 1h)。
27. 错误率告警查询用 sum(rate({env="prod"} |= "error" [5m])) by (service) / sum(rate({env="prod"}[5m])) by (service) > 0.05。
28. 排查慢请求用 {app="api"} | logfmt | duration > 1s | line_format "SLOW: {{.method}} {{.path}} {{.duration}}"。
29. 查 HTTP 5xx 详情用 {app="nginx"} | pattern `<ip> - - <_> "<method> <uri> <_>" <status> <bytes>` | status >= 500。
30. 检测凭据泄露用 {namespace="prod"} |~ `https?://\w+:\w+@`。
31. 通过 Grafana Alloy 采集文件日志：配置 loki.source.file 的 targets 为 [{__path__ = "/var/log/app/*.log", job = "app"}]，forward_to 到 loki.process.parse.receiver。
32. 在 Alloy 中用 loki.process 解析和过滤：stage.json expressions = { level = "level", msg = "message" }；stage.labels values = { level = "" }；stage.drop expression = ".*healthcheck.*"；forward_to 到 loki.write.cloud.receiver。
33. 在 Alloy 中用 loki.write 推送：endpoint url = "https://logs-xxx.grafana.net/loki/api/v1/push"，basic_auth username = sys.env("LOKI_USER")，password = sys.env("GRAFANA_API_KEY")，external_labels = { cluster = "prod" }。
34. 通过 Kubernetes 采集日志时配置 discovery.kubernetes role = "pod"，loki.source.kubernetes targets = discovery.kubernetes.pods.targets，forward_to = [loki.write.cloud.receiver]。
35. 通过 Loki HTTP Push API 推送日志：curl -X POST https://logs-xxx.grafana.net/loki/api/v1/push -u "user:apikey" -H 'Content-Type: application/json' -d '{"streams":[{"stream":{"app":"myapp","env":"prod"},"values":[["1609459200000000000","log line here"]]}]}'。
36. 理解推送路径：Client → Distributor → Ingester (WAL) → Object Storage (chunks)。
37. 理解读取路径：Query → Query Frontend → Querier → Ingester + Store (chunks)。
38. 掌握组件职责：Distributor 校验并哈希传入日志流；Ingester 在内存缓冲 chunks 并刷到对象存储；Querier 执行 LogQL；Query Frontend 缓存、拆分并并行化查询；Compactor 管理保留和去重。
39. 需要更多细节时查阅 references/logql.md、references/configuration.md、references/send-data.md。

适用边界 · 注意事项

• 未部署 Loki、Grafana Alloy/Promtail/Fluent Bit 或兼容 Loki 推送接口的日志系统时，无法直接使用这些查询和采集配置。
• 不要把它当全文索引搜索引擎：Loki 只索引 labels 不索引完整日志内容，非 label 字段过滤需要扫描 chunk，任意全文检索会变慢或变贵。
• 仅需查看单机少量本地日志且没有集中聚合、查询或告警需求时，引入 Loki 栈过重。