juwan-backend/docs/loki-usage-guide.md

Loki 使用指南（日志查看）

本文说明在当前项目中如何使用 Loki 查看 Kubernetes 日志，包括 Grafana 查询、LogQL 常用语句、命令行验证与常见排错。

---

1. 日志链路说明

当前日志链路：

• Promtail 采集节点日志文件
• Loki 存储与检索日志
• Grafana 作为查询与展示入口

相关配置文件：

• deploy/k8s/monitoring/promtail.yaml
• deploy/k8s/monitoring/loki.yaml
• deploy/k8s/monitoring/grafana.yaml

---

2. 快速开始（Grafana 查看日志）

步骤 1：确认监控组件运行

kubectl get pods -n monitoring

至少应看到 promtail、loki、grafana 为 Running。

步骤 2：打开 Grafana

kubectl port-forward -n monitoring svc/grafana 3000:3000

浏览器打开：http://localhost:3000

默认账号密码（按现有配置）：

• 用户名：admin
• 密码：change-me

步骤 3：进入 Explore 查询

• 左侧菜单进入 Explore
• 数据源选择 Loki
• 时间范围建议先设为 Last 6 hours 或 Last 24 hours
• 输入 LogQL 查询并点击 Run query

---

3. 常用 LogQL 查询语句

3.1 全量日志

{job="kubernetes-pods"}

3.2 按命名空间过滤

{job="kubernetes-pods", namespace="juwan"}

3.3 按服务（app 标签）过滤

{job="kubernetes-pods", app="user-rpc"}

3.4 多服务联合过滤

{job="kubernetes-pods", app=~"user-rpc|snowflake|email-mq"}

3.5 按容器名过滤

{job="kubernetes-pods", container="user-rpc"}

3.6 关键字过滤（错误日志）

{job="kubernetes-pods", namespace="juwan"} |= "error"

3.7 多关键字正则过滤

{job="kubernetes-pods", namespace="juwan"} |~ "(error|panic|fatal|timeout)"

3.8 统计最近 5 分钟错误量（按 app）

sum by (app) (count_over_time({job="kubernetes-pods"} |~ "(?i)error|panic|fatal" [5m]))

---

4. 不经过 Grafana 的直连验证（Loki API）

用于区分“Grafana 查询问题”与“日志未入库问题”。

4.1 端口转发 Loki

kubectl port-forward -n monitoring svc/loki 3100:3100

4.2 查询是否有流数据

curl "http://127.0.0.1:3100/loki/api/v1/query_range?query={job=\"kubernetes-pods\"}&limit=10"

4.3 查询 app 标签流

curl "http://127.0.0.1:3100/loki/api/v1/query_range?query={job=\"kubernetes-pods\",app=~\".+\"}&limit=10"

如果 API 返回 result 非空，说明 Loki 已正常入库。

---

5. 常见问题与处理

问题 1：Grafana 显示 No logs found

建议按顺序检查：

1. 时间范围是否太短（先调大到 6h/24h）
2. 查询标签是否过窄（先用 {job="kubernetes-pods"}）
3. Promtail 是否正常运行并有 target
4. Loki API 是否能直接查到数据

问题 2：Promtail 有 Running 但仍无日志

重点检查：

• promtail targets 是否 ready
• 是否存在 stat ... no such file or directory
• 是否挂载日志目录（/var/log 与 /var/lib/docker/containers）
• 是否有足够 RBAC 权限（pods/nodes/namespaces 等）

问题 3：查不到某个服务日志

建议检查：

• 该服务 pod 是否在运行并产生日志
• namespace 与 app 过滤条件是否正确
• 先用 namespace 过滤，再逐步加 app、container 条件

---

6. 推荐查询习惯

1. 先粗后细：全量 -> namespace -> app -> container -> 关键字
2. 先看时间范围：避免默认 1h 漏查
3. 遇到空结果先用 Loki API 验证入库
4. 保存常用查询到 Grafana Dashboard，便于团队复用

---

7. 参考

• Loki 故障排查文档：docs/loki-log-troubleshooting.md