Grafana Loki 配置参数完全参考：从 loki.yaml 到运行时热加载-二趣网

Grafana Loki 配置参数完全参考：从 loki.yaml 到运行时热加载

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

Grafana Loki 以 YAML 文件（通常称为loki.yaml）承载全部配置，涵盖服务端信息与按启动模式区分的各组件参数。本指南以 Loki 官方配置参考为骨架，结合当前仓库中的模板生成机制、CLI 标志定义与真实示例配置，系统讲解配置文件的加载规则、运行时打印技巧、环境变量展开、loki.yaml顶层配置块与全部子配置块、Runtime Configuration 热加载机制以及乱序写入（out-of-order）策略，帮助你在单体、微服务或 Helm 部署中正确编写、校验与调试 Loki 配置。

配置参考的生成与维护机制

Loki 的配置参考文档并非手工维护，而是由一个统一的模板文件生成。仓库中的 docs/templates/configuration.template 定义了文档的完整骨架（加载方式、环境变量、占位符、运行时配置、乱序写入等章节），而具体的配置项定义则被展开为共享文件 docs/sources/shared/configuration.md（本仓库中约 7700 行），再由 docs/sources/reference/loki-config-ref.md 通过{{< docs/shared lookup="configuration.md" ... >}}短代码引入。模板头部注释明确指出：如需修改文档内容，应修改模板文件并从仓库根目录执行make doc重新生成共享文件。这意味着你看到的每一个配置项、注释与默认值，都与pkg下各模块的RegisterFlags实现一一对应，是排查配置问题的第一手依据。

打印 Loki 运行时配置：快速定位配置问题

Loki 提供了两个极其有用的调试标志，可以在启动时把最终生效的完整配置对象打印出来：

-print-config-stderr：将整个配置对象输出到 stderr，适合直接运行./loki二进制时快速查看完整配置。
-log-config-reverse-order：以 Info 日志级别输出配置，且条目顺序被反转，使其在 Grafana Explore 中从上到下阅读时顺序正确——这是 Loki 官方在所有环境中运行时所使用的标志。

其执行逻辑定义在 pkg/loki/config_wrapper.go：Loki 在启动时会先用内置默认值构建配置对象，再用配置文件中的值覆盖默认值，最后用命令行标志覆盖配置文件的值。因此打印出来的是"合并后"的真实运行配置——所有配置项都有默认值（无论你是否使用），那些与你部署无关的存储配置也会出现，这是正常现象。当怀疑配置文件或标志没有被正确读取时，这个输出极具诊断价值。

配置文件加载规则

通过-config.file标志指定要加载的配置文件，其值可以是逗号分隔的多个路径，Loki 会使用第一个存在的文件。如果未指定-config.file，Loki 会在当前工作目录及config/子目录中查找config.yaml并使用之。

配置文件使用 YAML 格式编写，文档中以方括号（[]）表示参数为可选；对非列表参数而言，未设置时取默认值。

在配置中使用环境变量

该功能自 Loki 2.1 起可用。在启动命令中传入-config.expand-env=true（对应 pkg/loki/config_wrapper.go 中注册的-config.expand-env标志）后，即可在配置文件中使用：

${VAR}

其中VAR为环境变量名。每个变量引用会在启动时、YAML 解析之前被环境变量值替换，替换区分大小写。未定义的变量会被替换为空字符串，除非你指定默认值或自定义错误文本：

${VAR:-default_value}

default_value即环境变量未定义时使用的值。这一机制特别适合在部署时注入凭据、地址等需要按环境区分的值。

通用占位符（Generic placeholders）

配置参考中反复出现的类型占位符含义如下：

<boolean>：布尔值，可取true或false
<int>：普通整数（如0、1024、5000），或带可选单位后缀的字节数（如1024、256KB、64MB、4GB）。支持单位：B、KB、MB、GB、TB、PB、EB
<duration>：必须带单位后缀的时长。支持的单位取决于字段类型：Prometheus 时长字段支持ms、s、m、h、d、w、y（如30s、1m、1h、1d、1w）；Go 原生时长字段支持ns、us、µs、ms、s、m、h，但不支持d、w、y。注意0允许不带单位
<labelname>：匹配正则[a-zA-Z_][a-zA-Z0-9_]*的字符串
<labelvalue>：任意 Unicode 字符串
<filename>：相对当前工作目录的有效路径或绝对路径
<host>：由主机名或 IP 加可选端口组成的合法字符串
<string>：字符串
<secret>：表示机密（如密码）的字符串

`loki.yaml`顶层配置块总览

loki.yaml的顶层结构（默认值与 CLI 标志详见 docs/sources/shared/configuration.md 中### Supported contents and default values of loki.yaml一节）包括：

配置块	说明	关键默认值
`target`	要运行的组件列表，默认值`all`即单体模式；可用`-list-targets`标志列出全部可用 target	`"all"`
`auth_enabled`	是否启用基于`X-Scope-OrgID`头的认证；为`false`时 OrgID 恒为`-auth.no-auth-tenant`的值	`true`
`no_auth_tenant`	关闭认证时使用的租户 ID。默认`fake`为向后兼容；仅在全新集群上才建议修改，已有集群需先用`cmd/migrate`迁移旧租户路径下的数据	`"fake"`
`ballast_bytes`	预留的虚拟内存字节数，用于优化 GC。越大 GC 次数越少、CPU 开销越低，但会扭曲内存指标（不计物理内存，因为从不读取）	`0`
`server`	所启动模块的服务端配置	—
`distributor`/`querier`	分别配置 distributor 与 querier（querier 仅在运行全部模块或仅 querier 时适用）	—
`query_engine`	新一代查询引擎（实验性）：`enable`、`distributed`、`batch_size`（默认 100）、`prefetch_bytes`（默认 16KiB）、`worker_threads`（默认 0，即 GOMAXPROCS）等	默认关闭
`query_scheduler`/`frontend`/`query_range`	配置查询调度器、查询前端及其查询拆分与缓存	—
`ruler`/`ruler_storage`	配置 ruler 及其规则存储（后端支持`local`、`s3`、`gcs`、`azure`、`swift`、`filesystem`、`alibabacloud`、`bos`，默认`filesystem`）	—
`ingester`/`ingester_client`	配置 ingester 及其在 KV store 中的注册，以及 distributor 连接 ingester 的方式	—
`pattern_ingester`	模式提取器（默认关闭），包含`metric_aggregation`、`pattern_persistence`、`tee_config`等子块	`enabled: false`
`index_gateway`	索引网关：在无需频繁访问对象存储的前提下服务索引查询	—
`bloom_build`/`bloom_gateway`	（实验性）布隆过滤器构建与网关	—
`storage_config`/`chunk_store_config`/`schema_config`	配置索引与块存储后端、块缓存与落盘时机、块索引 schema 及其存放位置	—
`compactor`	压缩组件，用于合并索引分片	—
`limits_config`	全局与按租户限制，可在 runtime_config 文件的`overrides`中覆盖	—
`frontend_worker`	运行在 querier 内的工作进程，负责拾取并执行 query-frontend 入队的查询	—
`memberlist`	memberlist 客户端。只要配置了至少 1 个`join_members`，所有需要 ring 的组件都会自动选用 memberlist 类型的 kvstore	—
`kafka_config`	Kafka 写入/消费后端配置（`topic`、`reader_config`、`writer_config`、SASL 认证、consumer group、`auto_create_topic_enabled`默认`true`等）	—
`dataobj`	数据对象（dataobj）体系配置：`consumer`、`index`、`metastore`、`compaction`等（实验性）	`enabled: false`
`ingest_limits`	摄取限额服务：`active_window`（默认 2h）、`rate_window`（默认 5m）、`bucket_size`（默认 1m）、Kafka topic 分区数（默认 64）等	默认关闭
`runtime_config`	负责重载运行时配置文件的模块	—
`operational_config`	控制运行层面的行为（多用于调整日志冗长级别），可在 runtime_config 的`configs`中覆盖	—
`tracing`/`analytics`/`profiling`	分别配置追踪、匿名用量上报（`reporting_enabled`默认`true`，上报地址默认`https://stats.grafana.org/loki-usage-report`）与性能分析	—
`tenant_limits_allow_publish`	从租户限额端点发布的限额字段列表，为空则返回全部；使用 YAML 字段名（如`retention_period`、`max_query_series`）	见配置文档默认列表
`common`	多个模块共享的公共配置；若其他节给出更具体的配置，本节的对应配置会被忽略	—
`shutdown_delay`	收到 SIGTERM 与关停之间的等待时长；期间`/ready`端点返回 503	`0s`
`metrics_namespace`	指标命名空间（早期版本使用 cortex 命名空间），已弃用	`"loki"`

`common`配置块：单体部署的推荐入口

common用于在多个模块间共享配置，避免重复声明。典型用法见仓库自带的 cmd/loki/loki-local-config.yaml：

auth_enabled: false server: http_listen_port: 3100 grpc_listen_port: 9096 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 schema_config: configs: - from: 2020-10-24 store: tsdb object_store: filesystem schema: v13 index: prefix: index_ period: 24h

common下核心字段说明：

path_prefix：路径前缀（CLI 标志-common.path-prefix），所有本地文件（块、规则、WAL 等）的相对基准
storage：统一的存储后端声明，支持s3、gcs、azure、alibabacloud、bos、swift、cos、filesystem（含chunks_directory与rules_directory）及hedging（重复请求优化，at非零时在指定时长后发出第二个请求，up_to默认 2，max_per_second默认 5）、congestion_control（拥塞控制，strategy可选aimd，含start默认 2000、upper_bound默认 10000、backoff_factor默认 0.5）、object_store（基于 thanos-io/objstore 的客户端，需配合-use-thanos-objstore=true才生效）
ring：统一的 ring 配置，含kvstore.store（可选consul、etcd、inmemory、memberlist、multi，默认consul）、heartbeat_period（默认 15s）、heartbeat_timeout（默认 1m）、replication_factor（默认 3）、num_tokens（默认 128）、instance_id（默认主机名）、instance_interface_names、instance_port、zone_awareness_enabled等
compactor_address/compactor_grpc_address：compactor 的 HTTP/gRPC 地址，供其他组件发现 compactor
scratch_path：（实验性）临时数据路径

对象存储后端：从 S3 到文件系统

Loki 支持多种对象存储后端，均在 docs/sources/shared/configuration.md 中有独立配置块：

s3_storage_config：bucketnames、endpoint、region、access_key_id、secret_access_key、insecure（是否跳过 HTTPS 校验）、sse（服务端加密）、http_config、backoff_config、max_retries等
gcs_storage_config：bucket_name、chunk_buffer_size、request_timeout等
azure_storage_config：environment（AzureGlobal、AzureChinaCloud、AzureGermanCloud、AzureUSGovernment）、account_name、account_key、connection_string（可配合 SAS token 或 Azurite 模拟器）、container_name（默认loki）、use_managed_identity、use_service_principal、client_id/client_secret/tenant_id等
alibabacloud_storage_config：bucket、endpoint、region、access_key_id、secret_access_key、ram_role_name（ECS RAM 角色认证，需signature_version=v4）、signature_version（默认v1）等
bos_storage_config（百度 BOS）、swift_storage_config（OpenStack Swift）、cos_storage_config（IBM Cloud COS）以及**local_storage_config**（本地文件系统）
thanos_object_store_config：未来将作为对象存储客户端默认配置方式的统一入口，当前需-use-thanos-objstore=true启用

存储后端与 schema 的衔接由schema_config完成：每个configs条目声明from（生效起始日期）、store（索引存储，如tsdb）、object_store（块存储后端）、schema（schema 版本）、index的prefix与period。storage_config则配置具体索引与块存储的连接细节（如tsdb_shipper的active_index_directory、cache_ttl、shared_store等）。三者配合是 Loki 存储架构的核心，修改 schema 时须严格遵循向后兼容规则。

`limits_config`：全局与按租户限制

limits_config是运维中最重要的配置块之一，涵盖摄取、查询、保留三大类限制，常见参数包括：

摄取类：ingestion_rate_mb（每租户摄取速率）、ingestion_burst_size_mb、max_streams_per_user、max_global_streams_per_user、per_stream_rate_limit、per_stream_rate_limit_burst
查询类：max_query_length、max_query_lookback、max_query_series、max_entries_limit_per_query、query_timeout、max_query_bytes_read、max_chunks_per_query
保留与结构元数据：retention_period、retention_stream、structured_metadata_retention_period、discover_log_levels、discover_service_name、log_level_fields、otlp_config、pattern_persistence_enabled、metric_aggregation_enabled、volume_enabled/volume_max_series

这些值可通过 runtime config 文件的overrides按租户动态覆盖（详见下节），并可通过租户限额端点（tenant_limits_allow_publish控制发布字段）对外暴露。

Runtime Configuration：无需重启的热加载

Loki 支持"运行时配置"文件：在运行期间周期性重载，使运维人员无需重启即可调整部分配置。通过-runtime-config.file=<filename>标志指定文件，重载周期默认 10 秒，可用-runtime-config.reload-period=<duration>修改。目前使用运行时配置的两个组件是limits（限额）与multi KV store。也可在 YAML 中直接配置：

# 需要周期性检查并重载的配置文件 [file: <string>: default = empty] # 检查周期 [period: <duration>: default 10s]

示例运行时配置文件（注意multi_kv_config使用 kebab-case 键）：

overrides: tenant1: ingestion_rate_mb: 10 max_streams_per_user: 100000 max_chunks_per_query: 100000 tenant2: max_streams_per_user: 1000000 max_chunks_per_query: 1000000 multi_kv_config: mirror-enabled: false primary: consul

overrides中的字段即覆盖limits_config中同名配置；multi_kv_config则用于 multi 类型 kvstore 的主备切换（primary/secondary/mirror-enabled）。多租户场景下，这是动态调整单个租户限额的标准手段。

接受乱序写入（Out-of-order writes）

Loki 允许同一流（stream）的日志条目按时间乱序到达。允许的乱序深度由max_chunk_age控制（默认 2 小时，官方不建议调大）。Loki 按如下公式计算当前可接受的最早时间戳：

time_of_most_recent_line - (max_chunk_age/2)

即允许的乱序窗口为max_chunk_age的一半。晚于该最早时间的条目被接受；更早的条目返回too_far_behind错误。示例：若max_chunk_age为 2 小时，流{foo="bar"}在8:00有一条记录，则可接受的最早时间戳为8:00 - (2h / 2) = 7:00；若后续在10:00写入新行，最早时间戳随之变为9:00，窗口随最新行前移。理解此机制有助于在回填历史数据或客户端时间漂移时避免写入失败。

实战：结合示例配置快速起步

仓库提供了多套可直接参考的配置示例，是学习配置结构的活教材：

cmd/loki/loki-local-config.yaml：单机/单体模式，文件系统存储 + inmemory ring + TSDB schema v13 + 嵌入式结果缓存，适合本地开发与快速验证
cmd/loki/loki-docker-config.yaml：Docker 部署场景配置
cmd/loki/loki-local-multi-tenant-config.yaml：多租户单机配置
cmd/loki/loki-local-with-memcached.yaml：引入 memcached 缓存的本地配置
cmd/loki/loki-frontend.yaml、cmd/loki/loki-querier.yaml、cmd/loki/loki-index-gateway.yaml、cmd/loki/loki-bloom-gateway.yaml：微服务模式下各组件独立配置
cmd/loki/loki-overrides.yaml：运行时 overrides 示例
docs/sources/configure/ 目录下还包含大量分场景的配置示例（YAML）与说明文档，覆盖告警、运维、发送数据等主题的配置实践

结语

Loki 的配置体系"面广但规则统一"：所有参数都有默认值与对应 CLI 标志，可通过-print-config-stderr验证最终生效值；common块与schema_config/storage_config的配合决定了存储架构；limits_config配合 runtime config 的overrides实现了限额的动态调整。掌握 docs/sources/shared/configuration.md 这份约 7700 行的完整参考（其内容由 docs/templates/configuration.template 生成），再结合仓库内示例配置对照修改，即可从容应对从单体到微服务的各类部署与调优需求。

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析