FunctionalScaffold/docs/loki-quick-reference.md

Loki 快速参考

常用命令

服务管理

# 启动所有服务
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

健康检查

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

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

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

常用 LogQL 查询

基础查询

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

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

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

文本过滤

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

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

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

JSON 提取

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

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

聚合统计

# 日志数量
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 查询

查询日志

# 查询最近的日志
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'

查询标签

# 查询所有 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:

environment:
  - LOG_FILE_ENABLED=true

重启服务:

docker-compose up -d app

调整日志级别

编辑 deployment/docker-compose.yml:

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

修改保留期

编辑 monitoring/loki.yaml:

limits_config:
  retention_period: 72h  # 改为 3 天

重启 Loki:

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	-

故障排查

看不到日志

# 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 权限

sudo chmod 666 /var/run/docker.sock

清理日志数据

# 停止 Loki
docker-compose stop loki

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

# 重启 Loki
docker-compose start loki

性能优化

减少日志量

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

过滤健康检查日志

编辑 monitoring/promtail.yaml:

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

限制查询范围

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

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

文档链接

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