# 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：确认监控组件运行

```bash
kubectl get pods -n monitoring
```

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

### 步骤 2：打开 Grafana

```bash
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 全量日志

```logql
{job="kubernetes-pods"}
```

### 3.2 按命名空间过滤

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

### 3.3 按服务（app 标签）过滤

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

### 3.4 多服务联合过滤

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

### 3.5 按容器名过滤

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

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

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

### 3.7 多关键字正则过滤

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

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

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

---

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

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

### 4.1 端口转发 Loki

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

### 4.2 查询是否有流数据

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

### 4.3 查询 app 标签流

```bash
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`