Loki 快速上手教程:用 Docker Compose 部署单机 Loki 栈并掌握 LogQL 查询
Loki 快速上手教程:用 Docker Compose 部署单机 Loki 栈并掌握 LogQL 查询
本教程基于 tutorial.md 展开,带你在本地用 Docker Compose 一次性拉起 Loki + Grafana Alloy + Grafana 组成的完整日志观测栈(Loki stack),部署一个会持续产生日志的示例微服务应用,并通过 Grafana Logs Drilldown 与 Grafana Explore 完成从"看日志"到"写 LogQL 查询"的完整实践。读完本文,你将掌握单机(Monolithic)模式下 Loki 的部署方式、Alloy 日志采集链路的核心配置、Loki 主配置文件的各关键块含义,以及 logfmt 解析、标签过滤、指标查询等 LogQL 高频用法。
Loki Monolithic 模式架构图,展示了单进程内集成 Compactor、Distributor、Ingester、Query frontend、Querier、Ruler 等组件
前置准备
开始前,请确保本地已安装:
本教程假设你在 Linux 或 macOS 下操作;Windows 用户可通过 Windows Subsystem for Linux 执行同样的步骤。
提示:也可以直接在本教程对应的交互式学习环境(Killercoda 沙箱)中体验,该环境已预装全部依赖。
什么是 Loki 栈
Grafana Loki 只是 Grafana 日志观测栈中的一个组件。本教程所讲的 Loki stack 由三部分组成:
- Alloy:Grafana Alloy 是开源的遥测数据采集器,可采集指标、日志、链路追踪和持续剖析数据。在本教程中,Alloy 被配置为 tail 所有 Docker 容器的日志并转发给 Loki。
- Loki:日志聚合系统,负责存储采集到的日志,其定位"Like Prometheus, but for logs"——用标签索引而非全文索引,日志正文仅以压缩块存储。
- Grafana:开源的可观测性平台,用于查询和可视化 Loki 中存储的日志。
本教程采用 Loki 的 单机(Monolithic / single binary)模式部署,即所有微服务组件(Distributor、Ingester、Querier、Query frontend、Compactor、Ruler 等)在同一个进程内运行。按 deployment-modes.md 的说明,单机模式适合快速上手实验,以及每天约 20GB 以内的小规模读写;查询并行度受实例数与 max_query_parallelism 配置限制。
第一步:部署 Loki 栈
在本地部署 Loki 栈:
-
克隆 Loki 基础示例仓库并切换到
getting-started分支:git clone https://github.com/grafana/loki-fundamentals.git -b getting-started -
进入
loki-fundamentals目录:cd loki-fundamentals -
以
loki-fundamentals为当前目录,用 Docker Compose 拉起 Loki、Alloy 和 Grafana:docker compose up -d命令执行后应看到类似输出:
✔ Container loki-fundamentals-grafana-1 Started 0.3s ✔ Container loki-fundamentals-loki-1 Started 0.3s ✔ Container loki-fundamentals-alloy-1 Started 0.4s -
栈启动后,逐一验证各组件:
- Alloy:浏览器访问 http://localhost:12345/graph,可看到 Alloy UI(组件拓扑图)。
- Grafana:浏览器访问 http://localhost:3000,进入 Grafana 首页。
- Loki:浏览器访问 http://localhost:3100/metrics,可看到 Loki 的 Prometheus 指标页面。
第二步:用 Grafana Logs Drilldown 验证日志采集
由于 Alloy 被配置为 tail 所有 Docker 容器的日志,Loki 此刻应已在接收日志。最直观的验证方式是使用 Grafana Logs Drilldown(日志下钻)功能:访问 http://localhost:3000/drilldown,选择 Logs,即可进入 Drilldown 页面。
如果 Docker 环境中只部署了本教程的 demo,你会看到三个容器及其日志:loki-fundamentals-alloy-1、loki-fundamentals-grafana-1、loki-fundamentals-loki-1。点击 loki-fundamentals-loki-1 容器旁的 Show Logs,即可下钻查看该容器的日志详情。
本教程不展开 Logs Drilldown 的其余功能,更多用法参见 Grafana Logs Drilldown 官方文档。
第三步:部署示例应用并产生日志
当前 Loki 栈采集的是"关于自身的日志"。为了更贴近真实场景,可部署一个持续产生日志的示例应用——The Carnivorous Greenhouse(食虫植物温室),一个允许用户登录并模拟种植食虫植物的微服务应用,由七个服务组成:
- User Service:管理用户数据与认证(创建用户、登录)。
- Plant Service:管理植物创建,并在新植物创建时通知其他服务。
- Simulation Service:为每株植物生成传感器数据。
- WebSocket Service:管理应用的 WebSocket 连接。
- Bug Service:启用后随机让服务失败并产生额外日志。
- Main App:串联所有服务的主应用。
- Database:存储用户与植物数据的 PostgreSQL 数据库。
部署示例应用:
-
以
loki-fundamentals为当前目录,用 Docker Compose 构建并启动示例应用:docker compose -f greenhouse/docker-compose-micro.yml up -d --build注意:示例应用镜像需要现场构建,整个过程可能需要几分钟。
命令完成后应看到类似输出:
✔ Container greenhouse-websocket_service-1 Started 0.7s ✔ Container greenhouse-db-1 Started 0.7s ✔ Container greenhouse-user_service-1 Started 0.8s ✔ Container greenhouse-bug_service-1 Started 0.8s ✔ Container greenhouse-plant_service-1 Started 0.8s ✔ Container greenhouse-simulation_service-1 Started 0.7s ✔ Container greenhouse-main_app-1 Started 0.7s -
验证应用运行:浏览器访问 http://localhost:5005,应看到温室应用的登录页。
-
在应用中执行一些操作来产生日志:
- 创建用户:点击 Sign Up,填写用户名和密码后点击 Sign Up。
- 登录:用刚创建的用户名密码登录。
- 创建植物:登录后为植物命名、选择植物类型并点击 Add Plant,可重复多次。
-
产生日志后,回到 Grafana Logs Drilldown 页面 http://localhost:3000/drilldown,应能看到七个新服务,如
greenhouse-main_app-1、greenhouse-plant_service-1、greenhouse-user_service-1等。
第四步:用 Grafana Explore 查询日志
Logs Drilldown 已经能提供大量信息,但有时需要更主动地查询日志、提出更复杂的问题,这时用 Grafana Explore:
- 浏览器访问 http://localhost:3000 打开 Grafana。
- 从 Grafana 主菜单点击 Explore 图标进入 Explore 页。
- 在页面顶部的数据源菜单中选中 Loki 数据源,显示 Loki 查询编辑器。
- Loki 查询编辑器有两种模式:
- Builder 模式:可视化查询设计器。
- Code 模式:功能完善的 LogQL 编写器。
- 点击 Code 切换到 Code 模式,即可输入 LogQL 查询;将下面的查询粘贴进编辑器后点击 Run Query 执行。
示例查询 1:查看 container 标签值为 greenhouse-main_app-1 的全部日志行
{container="greenhouse-main_app-1"}
在 Loki 中,这被称为一个日志流(log stream)。Loki 使用 标签(labels) 作为描述日志流的元数据;Loki 查询总是以标签选择器开头,这里的标签选择器就是 {container="greenhouse-main_app-1"}。
示例查询 2:在上述流中筛选包含字符串 POST 的日志行
{container="greenhouse-main_app-1"} |= "POST"
从日志中提取属性(logfmt 解析)
Loki 设计上不强制日志行采用特定 schema——无论是 JSON、key-value 键值对、纯文本、Logfmt 还是其他格式,Loki 都将其作为字符流接收。示例应用使用 Logfmt 格式记录日志,例如:
ts=2025-02-21 16:09:42,176 level=INFO line=97 msg="192.168.65.1 - - [21/Feb/2025 16:09:42] "GET /static/style.css HTTP/1.1" 304 -"
逐段拆解:
ts=2025-02-21 16:09:42,176是日志行的时间戳。level=INFO是日志级别。line=97是代码中的行号。msg="..."是日志消息内容。
查询 Loki 时,可以把标签选择器的结果通过解析器(parser) 管道化,从日志行中提取属性以做进一步处理。例如把 {container="greenhouse-main_app-1"} 接入 logfmt 解析器,提取 level 和 line 属性:
{container="greenhouse-main_app-1"} | logfmt
执行后展开任意一条日志结果,即可看到提取出的属性字段。logfmt 是 LogQL 内置的解析器之一——从源码看,LogQL 语法中通过 LOGFMT 关键字触发 logfmtParser 与 logfmtExpressionParser(见 syntax.y),且支持 | logfmt label_extraction_expression 形式,即解析的同时按表达式提取指定标签。
提示:在进入下一节前,建议先在温室应用中把 Toggle Error Mode 开关置为 On,让 bug service 随机制造服务失败,以便产生 ERROR 级别日志供后续查询。
进阶查询与指标查询
启用 Error Mode 后,bug service 会让服务随机失败。接下来用 LogQL 追踪这些错误:
查询 1:解析出 level 属性并过滤 ERROR 级别日志
{container="greenhouse-plant_service-1"} | logfmt | level="ERROR"
该查询返回 greenhouse-plant_service-1 容器中 level 属性为 ERROR 的所有日志。
查询 2:进一步按代码行号过滤
{container="greenhouse-plant_service-1"} | logfmt | level="ERROR", line="58"
该查询返回同时满足 level="ERROR" 与 line="58" 的日志。注意这里的 | level="ERROR" 属于 LogQL 的标签过滤表达式(label filter),由 pipeline 中的 labelFilter 语法实现(见 syntax.y 附近与 label_filter.go),在解析器提取出结构化属性之后,再按属性值做行级过滤。
LogQL 还支持指标查询(metrics queries):将原始日志聚合为数值,从而在 Grafana 中使用更多可视化方式,并对日志生成告警。例如统计每秒产生指定属性日志的数量:
sum(rate({container="greenhouse-plant_service-1"} | logfmt | level="ERROR" [$__auto]))
由于错误量可能很低,建议把可视化类型从 lines 切换为 bars,以便观察错误率随时间的变化。
再如,统计错误率最高的前 10 个服务:
topk(10, sum(rate({env="production"} | logfmt | level="ERROR" [5m])) by (service_name))
注意:
service_name是 Loki 在日志行未提供服务名时自动生成的标签,默认取容器名作为服务名。所有自动生成的标签列表参见 labels 文档的"所有用户默认标签"一节。
最后,统计生产环境中每个容器的日志总吞吐量:
sum by (service_name) (rate({env="production"} | logfmt [$__auto]))
这条查询之所以成立,依赖于我们为日志行添加的 service_name 标签和 env 标签——其中 env 是 Alloy 在日志处理阶段为所有日志行添加的静态标签(见下文 Alloy 配置)。
深入幕后:Alloy 如何采集日志
至此,你已拥有一个运行中的 Loki 栈、一个持续产生日志的示例应用,并用 Logs Drilldown 与 Explore 查询过日志。下面深入了解日志采集链路、Loki 配置文件以及 Grafana 数据源配置。
Grafana Alloy 配置
Alloy 负责从所有 Docker 容器采集日志并转发给 Loki,它需要一个配置文件来声明"采集哪些日志、转发到哪里"。在 loki-fundamentals 目录下可以找到 config.alloy:
// 负责发现 Docker 环境中的新容器
discovery.docker "getting_started" {
host = "unix:///var/run/docker.sock"
refresh_interval = "5s"
}
// 负责对发现的容器进行 relabel
discovery.relabel "getting_started" {
targets = []
rule {
source_labels = ["__meta_docker_container_name"]
regex = "/(.*)"
target_label = "container"
}
}
// 负责从发现的容器采集日志
loki.source.docker "getting_started" {
host = "unix:///var/run/docker.sock"
targets = discovery.docker.getting_started.targets
forward_to = [loki.process.getting_started.receiver]
relabel_rules = discovery.relabel.getting_started.rules
refresh_interval = "5s"
}
// 负责处理日志(此处为添加静态标签)
loki.process "getting_started" {
stage.static_labels {
values = {
env = "production",
}
}
forward_to = [loki.write.getting_started.receiver]
}
// 负责将日志写入 Loki
loki.write "getting_started" {
endpoint {
url = "http://loki:3100/loki/api/v1/push"
}
}
// 启用 Alloy UI 中的实时日志查看
livedebugging {
enabled = true
}
这份配置可以通过 Alloy UI(http://localhost:12345/graph)以可视化拓扑图的形式查看各组件及其连接关系:
- discovery.docker:通过 Docker socket 查询 Docker 环境元数据,发现新容器并提供容器元数据。
- discovery.relabel:把元数据标签
__meta_docker_container_name转换成 Loki 标签container。 - loki.source.docker:从发现到的容器采集日志并转发给下一组件;它向
discovery.docker请求元数据,并应用discovery.relabel的 relabel 规则。 - loki.process:提供日志转换与提取的 stages,此处为所有日志添加静态标签
env=production。 - loki.write:把日志写入 Loki,转发到端点
http://loki:3100/loki/api/v1/push。
这套组件链路与仓库中 examples/getting-started/alloy-local-config.yaml 的写法一致:discovery.docker 发现容器 → discovery.relabel 生成 container 标签 → loki.source.docker 采集 → loki.write 推送。本教程演示环境额外用 loki.process 为日志统一打上 env=production 静态标签,这也是前文指标查询中 {env="production"} 选择器能成立的原因。
实时查看日志
Grafana Alloy 内置了实时日志查看器(livedebugging),可以在组件流水线的特定环节实时查看日志条目及其转换过程。打开浏览器访问:
http://localhost:12345/debug/loki.process.getting_started
即可观察 loki.process 组件处理中的实时日志流。
Loki 主配置文件解析
Loki 需要一个配置文件来定义自身如何运行。在 loki-fundamentals 目录下可找到 loki-config.yaml:
auth_enabled: false
server:
http_listen_port: 3100
grpc_listen_port: 9096
log_level: info
grpc_server_max_concurrent_streams: 1000
common:
instance_addr: 127.0.0.1
path_prefix: /tmp/loki
storage:
filesystem:
chunks_directory: /tmp/loki/chunks
rules_directory: /tmp/loki/rules
replication_factor: 1
ring:
kvstore:
store: inmemory
query_range:
results_cache:
cache:
embedded_cache:
enabled: true
max_size_mb: 100
limits_config:
metric_aggregation_enabled: true
allow_structured_metadata: true
volume_enabled: true
retention_period: 24h # 24h
schema_config:
configs:
- from: 2020-10-24
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
pattern_ingester:
enabled: true
metric_aggregation:
loki_address: localhost:3100
ruler:
enable_alertmanager_discovery: true
enable_api: true
frontend:
encoding: protobuf
compactor:
working_directory: /tmp/loki/retention
delete_request_store: filesystem
retention_enabled: true
逐块总结:
- auth_enabled:设为
false,表示 Loki 在写入与查询时不需要 租户 ID(多租户)。生产环境不建议如此;使用 Loki Helm chart 部署时默认设为true。 - server:定义 Loki 监听的端口(HTTP 3100、gRPC 9096)、日志级别,以及最大并发 gRPC 流数。
- common:Loki 的公共配置,包括实例地址、存储配置、复制因子和 ring 配置。这里使用
filesystem存储(chunks 与 rules 目录均位于/tmp/loki下),ring 的 KV 存储使用inmemory——这与单机模式一一对应。 - query_range:让 Loki 启用内置缓存(embedded_cache,最大 100MB)缓存查询结果。生产环境中一般由独立缓存服务(如 memcached)承担。
- limits_config:定义所有租户的全局限制,包括启用指标聚合(
metric_aggregation_enabled)、结构化元数据(allow_structured_metadata)、volume 查询(volume_enabled)以及 24 小时保留期(retention_period)。限制也可按租户细分,但属于进阶配置,多数场景全局限制已足够。 - schema_config:定义 Loki 的 schema 配置,包括 schema 版本(v13)、对象存储(filesystem)与索引配置(TSDB 索引,
index_前缀,周期 24h)。TSDB 是当前版本默认的索引存储(见 deployment-modes.md 中store: tsdb的使用方式)。 - pattern_ingester:启用 pattern ingester,用于发现日志模式,主要服务于 Grafana Logs Drilldown 的日志模式视图。
- ruler:启用 Loki 的 ruler 组件,用于基于日志查询创建告警。
- frontend:定义查询前端(query frontend)的编码格式,此处为
protobuf。 - compactor:定义 compactor 配置,用于压缩索引并管理 chunk 保留(
retention_enabled: true、工作目录与删除请求存储均为 filesystem)。
以上是 Loki 的基础配置。作为对照,仓库中的 examples/getting-started/loki-config.yaml 展示了更高阶的部署形态:使用 memberlist 作为 ring 的 KV 存储、S3 兼容对象存储(MinIO)作为 chunk 存储、store: tsdb 的 v13 schema,并通过 -target=read / -target=write / -target=backend 将单二进制拆成多个进程——这正是单机模式向 HA Monolithic / 微服务模式演进时配置文件的核心变化点。更完整的配置项请参阅 Loki 官方 Configuration 文档。
Grafana 中 Loki 数据源的配置
最后一块拼图是 Grafana 的 Loki 数据源——Grafana 通过它连接 Loki 并查询日志。Grafana 有多种定义数据源的方式:
- Direct(直接):在 Grafana UI 中手动定义数据源。
- Provisioning(预置):在配置文件中定义数据源,由 Grafana 启动时自动创建。
- API:通过 Grafana API 创建数据源。
本教程使用 Provisioning 方式,不挂载 Grafana 配置目录,而是在 docker-compose.yml 中通过覆盖 entrypoint 动态生成数据源配置:
grafana:
image: grafana/grafana:latest
environment:
- GF_FEATURE_TOGGLES_ENABLE=grafanaManagedRecordingRules
- GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
- GF_AUTH_ANONYMOUS_ENABLED=true
- GF_AUTH_BASIC_ENABLED=false
ports:
- 3000:3000/tcp
entrypoint:
- sh
- -euc
- |
mkdir -p /etc/grafana/provisioning/datasources
cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
apiVersion: 1
datasources:
- name: Loki
type: loki
access: proxy
orgId: 1
url: 'http://loki:3100'
basicAuth: false
isDefault: true
version: 1
editable: true
EOF
/run.sh
networks:
- loki
entrypoint 覆盖了默认启动命令:先创建数据源预置文件 ds.yaml,将 Loki 配置为默认数据源;随后调用 /run.sh——grafana/grafana 镜像内置的默认启动脚本,真正启动 Grafana 服务器。由于 Loki 与 Grafana 处于同一个 Docker 网络,数据源 URL 直接使用服务名 loki。作为对比,仓库示例 examples/getting-started/docker-compose.yaml 中多租户形态的数据源还会额外通过 httpHeaderName1: "X-Scope-OrgID" 与 httpHeaderValue1: "tenant1" 发送租户头——当 auth_enabled: true 时,请求必须携带 X-Scope-OrgID 指定租户。
Grafana Explore 中的 Loki 查询编辑器,支持 Builder/Code 模式切换与 Run Query 执行
下一步
你已经完成了 Loki Quickstart demo。接下来可以尝试:
- 部署(Deploy):Loki 支持多种部署方式,生产环境推荐通过 Helm chart 部署。
- 发送日志(Send Logs):本示例用 Grafana Alloy 采集日志,此外还有很多其他方式可按需选用,参见 send-data 文档。
- 查询日志(Query Logs):LogQL 是非常丰富的日志查询语言,包含大量提升日志检索与洞察的工具,参见 query 文档。
- 告警(Alert):可使用 Loki 的 ruler 组件基于日志查询创建告警,参见 alert 文档。
- 完整演示环境:如需运行包含 Mimir、Loki、Tempo、Grafana 的完整演示环境,可参考 intro-to-mlt 项目,它是一个自包含的学习环境,包含各组件详解与单实例部署的注释配置。