# Loki 快速参考

## 常用命令

### 服务管理

```bash
# 启动所有服务
cd deployment && docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f loki
docker-compose logs -f promtail

# 重启服务
docker-compose restart loki promtail

# 停止服务
docker-compose down
```

### 健康检查

```bash
# Loki
curl http://localhost:3100/ready

# Promtail
curl http://localhost:9080/ready

# 验证脚本
./scripts/verify_loki.sh
```

## 常用 LogQL 查询

### 基础查询

```logql
# 所有日志
{job="functional-scaffold-app"}

# 错误日志
{job="functional-scaffold-app", level="ERROR"}

# 特定时间范围
{job="functional-scaffold-app"}[5m]
```

### 文本过滤

```logql
# 包含文本
{job="functional-scaffold-app"} |= "error"

# 不包含文本
{job="functional-scaffold-app"} != "healthz"

# 正则匹配
{job="functional-scaffold-app"} |~ "error|exception"
```

### JSON 提取

```logql
# 提取 request_id
{job="functional-scaffold-app"} | json | request_id != ""

# 按 request_id 过滤
{job="functional-scaffold-app"} | json | request_id = "abc123"
```

### 聚合统计

```logql
# 日志数量
count_over_time({job="functional-scaffold-app"}[5m])

# 按级别统计
sum by (level) (count_over_time({job="functional-scaffold-app"}[5m]))

# 错误率
sum(rate({job="functional-scaffold-app", level="ERROR"}[5m]))
/
sum(rate({job="functional-scaffold-app"}[5m]))
```

## API 查询

### 查询日志

```bash
# 查询最近的日志
curl -G -s "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={job="functional-scaffold-app"}' \
  --data-urlencode 'limit=10' \
  | jq '.data.result'

# 查询错误日志
curl -G -s "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={job="functional-scaffold-app", level="ERROR"}' \
  | jq '.data.result'
```

### 查询标签

```bash
# 查询所有 job 标签值
curl -s "http://localhost:3100/loki/api/v1/label/job/values" | jq

# 查询所有 level 标签值
curl -s "http://localhost:3100/loki/api/v1/label/level/values" | jq
```

## 配置切换

### 启用文件日志

编辑 `deployment/docker-compose.yml`:

```yaml
environment:
  - LOG_FILE_ENABLED=true
```

重启服务:

```bash
docker-compose up -d app
```

### 调整日志级别

编辑 `deployment/docker-compose.yml`:

```yaml
environment:
  - LOG_LEVEL=WARNING  # DEBUG, INFO, WARNING, ERROR, CRITICAL
```

### 修改保留期

编辑 `monitoring/loki.yaml`:

```yaml
limits_config:
  retention_period: 72h  # 改为 3 天
```

重启 Loki:

```bash
docker-compose restart loki
```

## 访问地址

| 服务 | 地址 | 凭据 |
|------|------|------|
| Grafana | http://localhost:3000 | admin/admin |
| Loki API | http://localhost:3100 | - |
| Promtail | http://localhost:9080 | - |
| Prometheus | http://localhost:9090 | - |
| App | http://localhost:8111 | - |

## 故障排查

### 看不到日志

```bash
# 1. 检查 Promtail 日志
docker-compose logs promtail | tail -50

# 2. 检查容器标签
docker inspect deployment-app-1 | grep -A 5 Labels

# 3. 查询 Loki
curl -s "http://localhost:3100/loki/api/v1/label/job/values" | jq
```

### Docker socket 权限

```bash
sudo chmod 666 /var/run/docker.sock
```

### 清理日志数据

```bash
# 停止 Loki
docker-compose stop loki

# 清理数据
docker-compose exec loki rm -rf /loki/chunks/*

# 重启 Loki
docker-compose start loki
```

## 性能优化

### 减少日志量

```yaml
# docker-compose.yml
environment:
  - LOG_LEVEL=WARNING  # 只记录警告和错误
```

### 过滤健康检查日志

编辑 `monitoring/promtail.yaml`:

```yaml
pipeline_stages:
  - drop:
      expression: ".*healthz.*"
```

### 限制查询范围

```logql
# 好：限制时间范围
{job="functional-scaffold-app"}[5m]

# 差：查询所有时间
{job="functional-scaffold-app"}
```

## 文档链接

- 完整文档: `docs/loki-integration.md`
- 实施总结: `docs/loki-implementation-summary.md`
- 验证脚本: `scripts/verify_loki.sh`