Loki 快速上手教程:用 Docker Compose 部署单机 Loki 栈并掌握 LogQL 查询

原创2026-09-10 10:13:221,875 阅读
文章标签:日志分析可观测性后端云原生分布式数据库存储

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 栈:

  1. 克隆 Loki 基础示例仓库并切换到 getting-started 分支:

    git clone https://github.com/grafana/loki-fundamentals.git -b getting-started
    
  2. 进入 loki-fundamentals 目录:

    cd loki-fundamentals
    
  3. 以 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
    
  4. 栈启动后,逐一验证各组件:

第二步:用 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 数据库。

部署示例应用:

  1. 以 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
    
  2. 验证应用运行:浏览器访问 http://localhost:5005,应看到温室应用的登录页。

  3. 在应用中执行一些操作来产生日志:

    1. 创建用户:点击 Sign Up,填写用户名和密码后点击 Sign Up。
    2. 登录:用刚创建的用户名密码登录。
    3. 创建植物:登录后为植物命名、选择植物类型并点击 Add Plant,可重复多次。
  4. 产生日志后,回到 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:

  1. 浏览器访问 http://localhost:3000 打开 Grafana。
  2. 从 Grafana 主菜单点击 Explore 图标进入 Explore 页。
  3. 在页面顶部的数据源菜单中选中 Loki 数据源,显示 Loki 查询编辑器。
  4. Loki 查询编辑器有两种模式:
    • Builder 模式:可视化查询设计器。
    • Code 模式:功能完善的 LogQL 编写器。
  5. 点击 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 项目,它是一个自包含的学习环境,包含各组件详解与单实例部署的注释配置。
登录后查看全文
loki