2913 字
15 分钟
监控与可观测性:Loki+Promtail 日志聚合——像 Prometheus 一样管日志

那个一台台 SSH 上去 grep 的夜晚#

凌晨两点,服务报警,某个接口开始大面积返回 500。手边有六台服务器、二十多个容器,日志散在每一台机器上。于是开六个终端窗口,一个个 SSH 登录,docker logs 看最近输出,grep ERROR 翻关键字,再对着时间戳在脑子里把几台机器的日志拼成一条时间线。等拼明白,半小时过去了,故障窗口里最关键的那几分钟日志,还被新日志冲掉了一部分。

这种排障方式的问题不在手速,在于日志本身是「散装」的:没有统一入口、没有统一时间轴、没有跨机器检索。指标那边早就解决了这个问题——Prometheus 把所有机器的指标收拢到一处,Grafana 里一个面板看全局;日志这边却还停留在单机时代。这一篇要装的 Loki,干的正是把日志也收拢起来的事:每台机器、每个容器的日志实时汇到一个地方,在 Grafana 里和指标面板并排打开,按标签和关键字一查到底。

项目地址:https://github.com/grafana/loki

Loki 的设计:只给标签建索引#

Loki 是 Grafana Labs 出品的日志聚合系统,设计理念一句话概括:像 Prometheus 一样做日志。它和 Elasticsearch 那一派最大的区别在索引策略上。ELK 会把日志全文切词建索引,查什么都快,但索引本身往往比日志还大,内存和磁盘成本居高不下;Loki 反过来,只给标签(label)建索引,日志正文不做全文索引、压缩后整块存放,所以同一批日志在 Loki 里占用的存储通常比在 ELK 里低一个数量级,一台小内存的 VPS 就能跑得很稳。

代价也要说清楚:Loki 的查询是「先用标签把范围缩到某几个日志流,再在流内做文本过滤」,本质是带索引的 grep。它不适合拿任意关键词在全量日志里做秒级全文检索;但真实排障场景里,你几乎总是先知道「哪台机器、哪个服务、大概什么时间」,标签加时间窗已经把范围缩得足够小,流内过滤的速度完全够用。想清楚这个取舍,就理解了 Loki 的全部设计。

整套系统三个角色:

组件角色说明
Loki服务端接收、索引、存储、查询,HTTP 端口 3100
Promtail采集端装在每台机器上,读日志文件或容器日志,打好标签推给 Loki
Grafana查询端加 Loki 数据源后在 Explore 里查日志,与 Prometheus 面板同屏关联

Docker Compose 一把梭#

单机自用直接用官方的单体(monolithic)模式,一个 Loki 进程包办全部工作。下面这份 compose 把三件套都带上,Grafana 如果已经装过可以删掉那一段,只留 Loki+Promtail:

services:
loki:
image: grafana/loki:latest
container_name: loki
ports:
- "127.0.0.1:3100:3100"
volumes:
- ./loki-config.yaml:/etc/loki/local-config.yaml
- loki-data:/loki
command: -config.file=/etc/loki/local-config.yaml
restart: unless-stopped
promtail:
image: grafana/promtail:latest
container_name: promtail
volumes:
- ./promtail-config.yaml:/etc/promtail/config.yaml
- /var/run/docker.sock:/var/run/docker.sock:ro
- /var/log:/var/log:ro
command: -config.file=/etc/promtail/config.yaml
restart: unless-stopped
grafana:
image: grafana/grafana:latest
container_name: grafana
ports:
- "3000:3000"
volumes:
- grafana-data:/var/lib/grafana
restart: unless-stopped
volumes:
loki-data:
grafana-data:

注意 Loki 的端口绑了 127.0.0.1:它默认没有鉴权,不要把 3100 端口直接暴露到公网,远程写入靠反向代理加认证,或者干脆走内网和隧道。Promtail 挂了 Docker socket,是为了用服务发现自动盯上每个容器;这也意味着 Promtail 权限不低,配置文件要管好。

Loki 配置:存储与保留期#

loki-config.yaml 用单体模式的经典写法,存储先用本地 filesystem,个人和小团队规模完全够用,日后再迁对象存储也不难:

auth_enabled: false
server:
http_listen_port: 3100
common:
instance_addr: 127.0.0.1
path_prefix: /loki
storage:
filesystem:
chunks_directory: /loki/chunks
rules_directory: /loki/rules
replication_factor: 1
ring:
kvstore:
store: inmemory
schema_config:
configs:
- from: 2020-10-24
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
limits_config:
retention_period: 720h
compactor:
working_directory: /loki/compactor
delete_request_store: filesystem
retention_enabled: true

两个关键点。其一,索引用 TSDB schema(store: tsdb),这是官方现行推荐,网上老教程里的 boltdb-shipper 写法已经过时,照抄容易在新版本上启动失败。其二,保留期不是改一个数字就完事:retention_period 只是声明「想留多久」,真正执行删除的是 compactor,必须同时给它配上 retention_enabled: true 和删除请求存储。只写 retention_period 而不开 compactor,日志只进不出,磁盘迟早被撑满——这是新手最常见的坑。上面配的 720h 即 30 天,按自己的磁盘大小和排障习惯调整。

Promtail 配置:采集与打标签#

Promtail 是每台机器装一个的采集代理,负责三件事:发现日志在哪、给日志打标签、推给 Loki。配置里最重要的是 scrape_configs,下面给两个最常用的 job:一个用 Docker 服务发现自动采集全部容器日志,一个采集宿主机上的普通日志文件。

server:
http_listen_port: 9080
grpc_listen_port: 0
positions:
filename: /tmp/positions.yaml
clients:
- url: http://loki:3100/loki/api/v1/push
scrape_configs:
- job_name: docker
docker_sd_configs:
- host: unix:///var/run/docker.sock
refresh_interval: 5s
relabel_configs:
- source_labels: [__meta_docker_container_name]
regex: /(.*)
target_label: container
- source_labels: [__meta_docker_container_label_com_docker_compose_service]
target_label: service
pipeline_stages:
- docker: {}
- job_name: system
static_configs:
- targets: [localhost]
labels:
job: varlogs
host: server-01
__path__: /var/log/*.log

几点说明。positions 文件记录每个日志文件读到哪一行,Promtail 重启后从断点续读,不会把历史日志重推一遍。docker_sd_configs 会自动发现新容器,配合 relabel 把容器名、Compose 服务名提取成 container、service 标签,查日志时就靠它们定位。pipeline_stages 是流水线处理环节:docker: {} 把 Docker 的 JSON 日志外壳拆掉、只留正文和时间戳;日志本身是 JSON 格式的应用可以再加 json 阶段把字段抽出来,是纯文本的可以用 regex 阶段按正则提取等级、状态码等字段——抽出来的字段是查询时临时解析的「已解析字段」,不进索引,这一点和标签要分清。

文件型日志的轮转、截断等基础处理逻辑,可以和 Linux 日志管理篇 对照着看;而 Docker 自带的日志驱动与轮转配置,在 Docker 日志篇 里已经系统讲过,Promtail 是在那之上的集中化方案。

LogQL:查日志的语言#

LogQL 长得像 PromQL,分两段:前半段是流选择器,用标签圈定范围;后半段是管道,对圈进来的日志逐行过滤和解析。

# 圈定某个容器的日志流
{job="docker", container="nginx"}
# 在流内做文本包含过滤
{job="docker"} |= "error"
# 正则过滤,忽略大小写匹配超时与异常
{container=~"api-.*"} |~ "(?i)timeout|exception"
# JSON 日志:解析后按字段过滤
{job="docker"} | json | status >= 500
# 纯文本日志:按 logfmt 解析后过滤
{job="docker"} | logfmt | level="error"
# 还能当指标用:统计每 5 分钟的错误行数
rate({job="docker"} |= "error" [5m])

日常排障最顺手的组合是:先用 {host="...", container="..."} 把范围缩到出事的那个服务,把 Grafana 的时间窗拉到报警前后各十分钟,再 |= 关键字逐层收窄。最后那条 rate() 是 LogQL 的彩蛋——它把日志行数变成一条指标曲线,可以直接画进 Grafana 面板甚至配告警,等于日志顺手补上了指标的活。

在 Grafana 里和指标同屏#

Loki 装好后,在 Grafana 里加一个 Loki 数据源,地址填 http://loki:3100(同 compose 网络内用容器名即可),保存后进 Explore 就能跑上面的 LogQL。真正的杀手锏是关联:Prometheus 和 Loki 的标签体系是同一套思路,把两边同名标签对齐(比如都用 job、instance),就能在看指标面板时框选异常时间段,直接跳到同一时间窗的日志;反过来查日志时也能一键回到指标曲线。本系列 Grafana 篇 讲的面板与数据源基础在这里直接复用,指标、日志同屏之后,排障时在两个系统之间来回跳的次数明显减少。日志再往下走一步是链路追踪,三大支柱凑齐的思路见 链路追踪篇。

标签设计:低基数是红线#

Loki 的一切性能都建立在「日志流数量可控」上:每一组不同的标签组合就是一条独立的流,流越多,索引越大、查询越慢。标签该放什么、不该放什么,是用 Loki 的第一纪律。

WARNING

标签只放低基数维度:job、host、container、service、level 这类取值有限的字段。绝对不要把用户 ID、请求 ID、订单号、IP 地址这类高基数字段放进标签——每多一个取值就多一条流,几万个请求 ID 就能把索引撑爆,这是 Loki 头号事故,官方文档反复警告。需要按请求 ID 查时,把它留给管道过滤(|= 或解析字段),那才是它的正确位置。

判断标准很简单:这个字段的全部可能取值能不能数得过来?服务名、主机名、日志等级可以,用户 ID、追踪 ID 不行。拿不准的字段一律先不打标签,用 | json、| logfmt 在查询时临时解析,等确认取值确实有限再提升为标签也不迟。

排障#

Promtail 读不到 Docker 日志。 先查三件事:compose 里 /var/run/docker.sock 有没有挂进去;Promtail 容器内的用户对 socket 有没有读权限(宿主机上 socket 的属组权限经常是元凶);打开 Promtail 自己的 http://localhost:9080/targets 页面,看目标是不是 active、last error 写了什么。文件型日志读不到同理,先看 targets 页和 positions 文件是否可写。

Grafana 里查不到日志。 十有八九不是丢了,是没查对。先确认流选择器的标签和 Promtail 实际打的标签完全一致(标签名拼写、值都对上),再确认 Grafana 右上角的时间范围覆盖日志产生的时间——LogQL 查询严格按时间窗走,差一分钟都查不到。还不行就用 Loki 的接口直接验证:curl 'http://localhost:3100/loki/api/v1/labels' 看标签在不在,逐层缩小问题范围。

Loki 启动就报配置错误。 多数是版本与 schema 不匹配:新版本镜像配了老教程的配置(boltdb-shipper、过时的 schema 版本号)最容易翻车。对策是配置以你实际拉取的镜像版本对应的官方文档为准,改 schema 时只新增一段 configs、不要改动已生效的历史段,索引段一旦写错,老数据就查不出来了。

磁盘涨得比预期快。 先算流的数量:标签基数失控时,chunk 文件会碎成海量小文件。去 Grafana 里用 {job=~".+"} 配合 count_over_time 粗看各流的量,或者直接查 Loki 的 /metrics 里按流统计的指标,揪出异常膨胀的标签组合。

小结#

Loki 的取舍非常清晰:放弃全文索引,换来极低的存储与运维成本,用「标签缩小范围+管道过滤」覆盖绝大多数真实排障场景。如果你本来就在用 Prometheus+Grafana,它几乎是零学习成本的补完——同一套标签哲学、同一套标签哲学、同一个 Grafana、同一套时间窗。已经在用 ELK 且依赖全文检索与复杂聚合的团队没必要迁;但如果你的日志还散在各台机器上、或者 ELK 的资源开销让你肉疼,Loki 是目前最省心的答案。把日志收拢到一处、和指标同屏、按标签一查到底,凌晨两点排障时,日志和指标终于有了同一个入口,那种开六个终端拼时间线的日子,就算是翻篇了。

监控与可观测性:Loki+Promtail 日志聚合——像 Prometheus 一样管日志
https://www.anexns.cloudns.org/posts/monitoring-loki/
作者
Anexns
发布于
2026-11-16
许可协议
CC BY-NC-SA 4.0