文档 Grafana Loki 设置 升级

升级 Loki

我们尽一切努力保持 Grafana Loki 向后兼容，以便升级风险低、摩擦小。

不幸的是，Loki 是一款软件，软件开发不易，有时我们不得不在易用性和易维护性之间做出权衡。

如果我们在升级时遇到任何预期困难，将在此处记录。

随着发布的版本越来越多，一次性跨多个版本升级时，意外问题出现的可能性也会增加。如果可能，请尽量保持最新并按顺序进行升级。如果您想跳过版本，请在尝试升级生产环境之前先在开发环境中进行测试。

检查配置更改

使用 Docker，您可以通过以下命令检查 Loki 两个版本之间的更改

bash 复制

export OLD_LOKI=2.9.4
export NEW_LOKI=3.0.0
export CONFIG_FILE=local-config.yaml
diff --color=always --side-by-side <(docker run --rm -t -v "${PWD}":/config grafana/loki:${OLD_LOKI} -config.file=/etc/loki/${CONFIG_FILE} -print-config-stderr 2>&1 | sed '/Starting Loki/q' | tr -d '\r') <(docker run --rm -t -v "${PWD}":/config grafana/loki:${NEW_LOKI} -config.file=/etc/loki/${CONFIG_FILE} -print-config-stderr 2>&1 | sed '/Starting Loki/q' | tr -d '\r') | less -R

对于大多数人来说，tr -d '\r' 可能不是必需的，似乎 WSL2 偷偷加入了某些 Windows 换行符...

输出信息非常详细，因为它显示了用于运行 Loki 的整个内部配置结构。如果您只想查看更改或需要不同风格的输出，可以使用 diff 命令进行尝试。

Main / 未发布版本

3.4.0

Loki 3.4.0

新的对象存储客户端

Loki 3.4.0 版本引入了基于 Thanos Object Storage Client Go 模块 的新对象存储客户端，这是一个可选功能。在未来的版本中，这将成为配置存储的默认方式，并且现有的存储客户端将被弃用。

新的存储配置与现有格式不同。请参阅Thanos 存储配置参考，查看支持的存储提供商及其配置选项的完整列表。

文档现在还包含了迁移指南和配置示例，以便使用基于 Thanos 的存储客户端。

3.3.0

Loki 3.3.0

实验性 Bloom 过滤器

在 Loki 3.3.0 版本中，bloom 块格式发生了变化，之前创建的任何块都与新格式不兼容。在升级之前，我们建议删除对象存储中所有现有的 bloom 块。我们将 bloom 块和元数据存储在配置的对象存储的 bloom 路径中。要清除所有 bloom 块，请删除对象存储中 bloom 路径内的所有对象。

3.2.0

Loki 3.2.0

HTTP API

即时查询的 API 端点 /api/v1/query 现在在提供的 query 参数包含日志选择器查询时返回 HTTP 状态 400（Bad Request），而不是返回不一致的结果。请改用范围查询端点 /api/v1/query_range（Grafana Explore 中的 Range 类型）。

配置

Loki 将 -ruler.alertmanager-use-v2 的默认值从 false 更改为 true。Alertmanager APIv1 已在 Alertmanager 0.16.0 中弃用，并在 0.27.0 中移除。

实验性 Bloom 过滤器

用于构建 bloom 过滤器块以加速查询的 bloom compactor 组件已被移除，取而代之的是两个新组件：bloom planner 和 bloom builder。有关更多信息，请查阅使用 Bloom 加速查询文档。

在此次变更中移除的每个租户设置的 CLI 参数（及其对应的 YAML 设置）

• -bloom-compactor.enable-compaction
• -bloom-compactor.shard-size
• -bloom-compactor.shard-size
• -bloom-compactor.shard-size

在此次变更中已移至不同前缀的每个租户设置的 CLI 参数

• -bloom-compactor.max-page-size 已更改为 -bloom-builder.max-page-size
• -bloom-compactor.max-block-size 已更改为 -bloom-builder.max-block-size
• -bloom-compactor.ngram-length 已更改为 -bloom-builder.ngram-length
• -bloom-compactor.ngram-skip 已更改为 -bloom-builder.ngram-skip
• -bloom-compactor.false-positive-rate 已更改为 -bloom-builder.false-positive-rate
• -bloom-compactor.block-encoding 已更改为 -bloom-builder.block-encoding

它们在 limits_config 块中的 YAML 对应设置保持不变。

所有其他带有 -bloom-compactor. 前缀的 CLI 参数（及其对应的 YAML 设置）均已移除。

3.0.0

Loki 3.0 是一个主要版本升级，包含多项重大变更。

以下是我们认为大多数用户可能遇到的主要事项列表

• 默认启用结构化元数据，并且需要 tsdb 和 v13 schema，否则 Loki 将无法启动。请参阅结构化元数据、Open Telemetry、Schema 和索引。
• 已移除 shared_store 配置。请参阅从 shipper 配置中移除 shared_store 和 shared_store_key_prefix。
• Loki 现在默认强制执行最大行大小 256KB（您可以禁用或增加此限制，但这是 Grafana Labs 运行 Loki 的方式）。请参阅默认配置值的更改。
• Loki 现在对每个时间序列强制执行最大标签限制为 15 个，之前是 30 个。额外的标签会增加索引大小并降低性能，您几乎不需要超过 15 个标签。请参阅默认配置值的更改。
• Loki 在摄取时将默认自动尝试填充 service_name 标签。请参阅service_name 标签。
• 存在多项指标名称更改。请参阅Distributor 指标更改、嵌入式缓存指标更改和指标命名空间。

如果您想查看现有配置是否适用于 Loki 3.0

1. 在您计算机上的空目录中，将您的配置复制到名为 loki-config.yaml 的文件中。
2. 在该目录中运行此命令

bash 复制

docker run --rm -t -v "${PWD}":/config grafana/loki:3.0.0 -config.file=/config/loki-config.yaml -verify-config=true

Helm Chart 发生了一些重大变更，并有单独的升级指南：升级到 Helm 6.x。

Loki 3.0.0

结构化元数据、Open Telemetry、Schema 和索引

Loki 3.0 的一项旗舰功能是原生支持 Open Telemetry Protocol (OTLP)。这得益于 Loki 中的一项新功能，称为结构化元数据，用于存放不属于标签或日志行的元数据。OTel 资源和属性通常是既不属于索引也不属于日志行的优秀数据示例。

Loki 3.0 中默认启用结构化元数据，但它要求您当前的 schema 同时使用 tsdb 索引类型和 v13 存储 schema。如果您没有同时使用这两者，您有两种选择

• 在更新到 3.0 之前升级您的索引版本和 schema 版本，请参阅schema 配置升级。
• 禁用结构化元数据（以及 OTLP 支持），升级到 3.0 后再执行 schema 迁移。这可以通过在 limits_config 部分设置 allow_structured_metadata: false 或设置命令行参数 -validation.allow-structured-metadata=false 来完成。

service_name 标签

Loki 3.0 默认将自动为所有摄取的日志分配一个 service_name 标签。服务名称是 Open Telemetry 语义约定所要求的，也是 Grafana Labs 正在构建到未来用户界面和查询体验中的内容。

Loki 将按照以下顺序查找标签，尝试创建 service_name 标签

• service_name
• service
• app
• application
• name
• app_kubernetes_io_name
• container
• container_name
• component
• workload
• job

如果在列表中没有找到匹配的标签，则应用值 unknown_service。

您可以通过在limits_config 块中向 discover_service_name 提供标签列表来更改此列表。

您可以通过为 discover_service_name 提供一个空值来禁用此功能。

从 shipper 配置中移除 shared_store 和 shared_store_key_prefix

以下用于配置 TSDB 和 BoltDB shipper 的共享存储的 CLI 标志及其对应的 YAML 设置现已移除

• -boltdb.shipper.shared-store
• -tsdb.shipper.shared-store

今后，period_config 中的 object_store 设置将用于配置索引存储。这强制要求给定周期内的块和索引文件驻留在同一个存储桶中。

我们移除共享存储设置是为了简化存储配置并减少错误配置的可能性。

• 如果您之前未配置 -boltdb.shipper.shared-store、-tsdb.shipper.shared-store 或其对应的 YAML 设置，则升级过程中无需进行任何更改。
• 如果您已配置 -boltdb.shipper.shared-store 或其 YAML 设置
  • 如果它与使用 boltdb-shipper 作为索引类型的所有周期的 object_store 值匹配，则除了移除已删除配置选项的使用外，无需进行其他更改。
  • 如果存在不匹配，您将丢失 -boltdb.shipper.shared-store 与 object_store 不匹配的周期的索引访问权限。
    • 为了使这些索引可查询，需要将索引表移动或复制到 object_store 中配置的存储。
• 如果您已配置 -tsdb.shipper.shared-store 或其 YAML 设置
  • 如果它与使用 tsdb 作为索引类型的所有周期的 object_store 值匹配，则除了移除已删除配置选项的使用外，无需进行其他更改。
  • 如果存在不匹配，您将丢失 -tsdb.shipper.shared-store 与 object_store 不匹配的周期的索引访问权限。
    • 为了使这些索引可查询，需要将索引表移动或复制到 object_store 中配置的存储。

以下用于配置 TSDB 和 BoltDB shipper 路径前缀的 CLI 标志及其对应的 YAML 设置现已移除

• -boltdb.shipper.shared-store.key-prefix
• -tsdb.shipper.shared-store.key-prefix

现在可以通过在 period_config 的 index 键下设置 path_prefix 来配置存储索引的路径前缀。这使用户能够通过添加新的 period config 来更改路径前缀。

yaml 复制

period_config:
  index:
    path_prefix: "index/"
    period: 24h

path_prefix 默认为 index/，这与已移除配置的默认值相同。

• 如果您之前未配置 -boltdb.shipper.shared-store.key-prefix、-tsdb.shipper.shared-store.key-prefix 或其对应的 YAML 设置，则无需进行任何更改。
• 如果您已将 -boltdb.shipper.shared-store.key-prefix 或其 YAML 设置配置为 index/ 之外的值，请确保所有使用 boltdb-shipper 作为索引的现有 period configs 都将 path_prefix 设置为之前配置的值。
• 如果您已将 -tsdb.shipper.shared-store.key-prefix 或其 YAML 设置配置为 index/ 之外的值，请确保所有使用 tsdb 作为索引的现有 period configs 都将 path_prefix 设置为之前配置的值。

从 compactor 配置中移除 shared_store 和 shared_store_key_prefix

以下用于配置 compactor 共享存储和路径前缀的 CLI 标志及其对应的 YAML 设置现已移除

• -boltdb.shipper.compactor.shared-store
• -boltdb.shipper.compactor.shared-store.key-prefix

今后，compactor 将在 period configs 中配置的所有索引类型为 tsdb 或 boltdb-shipper 的对象存储上运行压缩和保留。

应明确配置 delete_request_store

启用保留时，应明确配置 -compactor.delete-request-store 或其 YAML 设置，这是存储删除请求所必需的。删除请求存储的路径前缀由 -compactor.delete-request-store.key-prefix 决定，默认为 index/。

配置 async_cache_write_back_concurrency 和 async_cache_write_back_buffer_size 已移除

这些配置与 cache-config 中的 Background 配置重复。

async_cache_write_back_concurrency 可以通过 writeback_goroutines 设置，async_cache_write_back_buffer_size 可以通过 writeback_buffer 设置

此外，Background 配置还允许您设置 writeback_size_limit，可用于设置写入回写对象使用的最大内存量，而非对象数量。

旧版 ingester 关机处理程序已移除

已弃用的处理程序 /ingester/flush_shutdown 已移除，请改用 /ingester/shutdown?flush=true。

Ingester 配置 max_transfer_retries 已移除

已移除设置 max_transfer_retries (-ingester.max-transfer-retries)，以支持预写日志 (WAL)。在滚动重启期间，旧 ingester 关闭时，该设置用于允许将块传输到新的 ingester。此设置的替代方案是

• A. (推荐) 启用 WAL 并依赖新的 ingester 重放 WAL。
  • 可选地，您可以启用 flush_on_shutdown (-ingester.flush-on-shutdown) 以在关机时刷新到长期存储。
• B. 通过 ingester /shutdown?flush=true 端点在关机期间手动刷新。

移除运行时覆盖配置文件的 default 部分

此部分在 2.9 版本中引入，可能未被广泛使用。仅当您使用运行时配置文件运行 Loki 且已在 2.9 版本中填充了新增的 default 块时，此更改才会影响您。

已移除 default 块，取而代之的是在标准 Loki 配置中新增了一个顶级配置 operational_config，您可以在此处为运行时配置设置默认值。

配置 use_boltdb_shipper_as_backup 已移除

设置 use_boltdb_shipper_as_backup (-tsdb.shipper.use-boltdb-shipper-as-backup) 是 TSDB 存储开发中的遗留物。在 TSDB 仍处于高度实验阶段时，它被用于允许同时写入 TSDB 和 BoltDB。由于 TSDB 现在已经稳定并成为推荐的索引类型，该设置已变得无关紧要，因此被移除。应用之前的默认值 false。

已弃用的配置选项已移除

1. 已移除已弃用的 store.max-look-back-period CLI 标志及其对应的 YAML 设置。请改用 querier.max-query-lookback 配置。
2. 移除已弃用的 -querier.engine.timeout CLI 标志及其对应的 YAML 设置。
3. 还从 querier YAML 部分移除了 query_timeout。您现在在 Limits Config 中配置 query_timeout，而不是在 querier 下进行配置。
4. s3.sse-encryption 已移除。AWS 现在默认将所有存储桶的加密设置为 SSE-S3。请使用 sse.type 设置 SSE 类型。
5. ruler.wal-cleaer.period 已移除。请改用 ruler.wal-cleaner.period。
6. experimental.ruler.enable-api 已移除。请改用 ruler.enable-api。
7. split_queries_by_interval 已从 query_range YAML 部分移除。您现在可以在 Limits Config 中进行配置。
8. frontend.forward-headers-list CLI 标志及其对应的 YAML 设置已移除。
9. frontend.cache-split-interval CLI 标志已移除。结果缓存间隔现在由 querier.split-queries-by-interval 决定。
10. querier.worker-parallelism CLI 标志及其对应的 yaml 设置现已移除，因为它对已存在的 querier.max-concurrent 没有额外价值。我们建议配置 querier.max-concurrent 来限制查询器处理的最大并发请求数。
11. ruler.evaluation-delay-duration CLI 标志及其对应的 YAML 设置已移除。
12. validation.enforce-metric-name CLI 标志及其对应的 YAML 设置已移除。
13. boltdb.shipper.compactor.deletion-mode CLI 标志及其对应的 YAML 设置已移除。您现在可以在 Limits Config 中配置 compactor.deletion-mode CLI 标志或 deletion_mode YAML 设置。
14. 使用 boltdb.shipper.compactor. 前缀的 Compactor CLI 标志已移除。您可以改用带有 compactor. 前缀的 CLI 标志。

Distributor 指标更改

已移除指标 loki_distributor_ingester_append_failures_total，取而代之的是 loki_distributor_ingester_append_timeouts_total。这个新指标能更清晰地指示 ingester 存在问题，可用于高信号告警。

3.0 版本默认配置值的更改

默认启用自动流分片

自动流分片有助于在高流量流的写入负载在 ingester 之间保持平衡，并有助于避免热点。有关更多信息，请查看操作页面

默认启用更多结果缓存

TSDB 索引类型支持对“统计信息”（stats）和“容量”（volume）查询结果进行缓存，现在默认启用此功能。

“标签”（label）和“时间序列”（series）请求现在也可以缓存，此功能默认启用。

所有这些都缓存到 results_cache 中，该缓存配置在 query_range 配置部分。默认情况下，使用内存缓存。

写入去重缓存已弃用

写入去重缓存已弃用，因为它不适用于较新的单存储索引（TSDB 和 boltdb-shipper）。如果您使用的是旧版索引类型，请考虑迁移到 TSDB（推荐）。

嵌入式缓存指标更改

• 已移除以下嵌入式缓存指标。请改用 loki_cache_fetched_keys、loki_cache_hits、loki_cache_request_duration_seconds，它们衡量对配置缓存（embeddedcache、memcached 或 redis）发出的请求。

  • querier_cache_added_total
  • querier_cache_gets_total
  • querier_cache_misses_total

• 以下嵌入式缓存指标已重命名

  • querier_cache_added_new_total 已重命名为 loki_embeddedcache_added_new_total
  • querier_cache_evicted_total 已重命名为 loki_embeddedcache_evicted_total
  • querier_cache_entries 已重命名为 loki_embeddedcache_entries
  • querier_cache_memory_bytes 已重命名为 loki_embeddedcache_memory_bytes

• 已弃用指标 querier_cache_stale_gets_total 现已移除。

指标命名空间

一些 Loki 指标之前以 cortex_ 前缀开头。在此版本中，它们将更改为以 loki_ 开头。要保留 cortex_ 前缀，请将 metrics_namespace 从默认的 loki 更改为 cortex。以下指标将发生更改

• cortex_distributor_ingester_clients
• cortex_dns_failures_total
• cortex_dns_lookups_total
• cortex_dns_provider_results
• cortex_frontend_query_range_duration_seconds_bucket
• cortex_frontend_query_range_duration_seconds_count
• cortex_frontend_query_range_duration_seconds_sum
• cortex_ingester_flush_queue_length
• cortex_kv_request_duration_seconds_bucket
• cortex_kv_request_duration_seconds_count
• cortex_kv_request_duration_seconds_sum
• cortex_member_consul_heartbeats_total
• cortex_prometheus_last_evaluation_samples
• cortex_prometheus_notifications_alertmanagers_discovered
• cortex_prometheus_notifications_dropped_total
• cortex_prometheus_notifications_errors_total
• cortex_prometheus_notifications_latency_seconds
• cortex_prometheus_notifications_latency_seconds_count
• cortex_prometheus_notifications_latency_seconds_sum
• cortex_prometheus_notifications_queue_capacity
• cortex_prometheus_notifications_queue_length
• cortex_prometheus_notifications_sent_total
• cortex_prometheus_rule_evaluation_duration_seconds
• cortex_prometheus_rule_evaluation_duration_seconds_count
• cortex_prometheus_rule_evaluation_duration_seconds_sum
• cortex_prometheus_rule_evaluation_failures_total
• cortex_prometheus_rule_evaluations_total
• cortex_prometheus_rule_group_duration_seconds
• cortex_prometheus_rule_group_duration_seconds_count
• cortex_prometheus_rule_group_duration_seconds_sum
• cortex_prometheus_rule_group_interval_seconds
• cortex_prometheus_rule_group_iterations_missed_total
• cortex_prometheus_rule_group_iterations_total
• cortex_prometheus_rule_group_last_duration_seconds
• cortex_prometheus_rule_group_last_evaluation_timestamp_seconds
• cortex_prometheus_rule_group_rules
• cortex_query_frontend_connected_schedulers
• cortex_query_frontend_queries_in_progress
• cortex_query_frontend_retries_bucket
• cortex_query_frontend_retries_count
• cortex_query_frontend_retries_sum
• cortex_query_scheduler_connected_frontend_clients
• cortex_query_scheduler_connected_querier_clients
• cortex_query_scheduler_inflight_requests
• cortex_query_scheduler_inflight_requests_count
• cortex_query_scheduler_inflight_requests_sum
• cortex_query_scheduler_queue_duration_seconds_bucket
• cortex_query_scheduler_queue_duration_seconds_count
• cortex_query_scheduler_queue_duration_seconds_sum
• cortex_query_scheduler_queue_length
• cortex_query_scheduler_running
• cortex_ring_member_heartbeats_total
• cortex_ring_member_tokens_owned
• cortex_ring_member_tokens_to_own
• cortex_ring_members
• cortex_ring_oldest_member_timestamp
• cortex_ring_tokens_total
• cortex_ruler_client_request_duration_seconds_bucket
• cortex_ruler_client_request_duration_seconds_count
• cortex_ruler_client_request_duration_seconds_sum
• cortex_ruler_clients
• cortex_ruler_config_last_reload_successful
• cortex_ruler_config_last_reload_successful_seconds
• cortex_ruler_config_updates_total
• cortex_ruler_managers_total
• cortex_ruler_ring_check_errors_total
• cortex_ruler_sync_rules_total

metrics_namespace 设置已弃用。它将在下一个次版本中移除。届时默认前缀将是 loki。

LogCLI

用于检索远程 schema 的存储

以前，当 -remote-schema 设置为 true 时，LogCLI 会从 -boltdb.shipper.shared-store 中配置的存储检索远程 schema。现引入新的 CLI 标志 -schema-store 作为替代，用于配置检索远程 schema 的存储。

2.9.0

Loki 2.9.0

Index gateway 随机分片

关机标记文件

/ingester/prepare_shutdown 端点可以写入一个关机标记文件。如果新的 ingester.shutdown_marker_path 配置设置有值，则使用该值。否则，如果 common.path_prefix 配置设置有值，则使用该值。否则，在启动时会在日志中显示警告，并且 /ingester/prepare_shutdown 端点将返回 500 状态码。

Compactor 多存储支持

在之前的版本中，设置 -boltdb.shipper.compactor.shared-store 会配置以下内容

用于管理删除请求的存储。

应执行索引压缩的存储。

如果未设置 -boltdb.shipper.compactor.shared-store，它会默认为使用 tsdb 或 boltdb-shipper 索引的最新 period_config 中配置的 object_store。

Compactor 现在支持在多个存储桶/对象存储上执行索引压缩。并且今后 Loki 将不会对 -boltdb.shipper.compactor.shared-store 设置任何默认值，这会带来一些副作用，详情如下

应执行索引压缩的存储

如果用户配置了 -boltdb.shipper.compactor.shared-store，则 Loki 将仅在该配置指定的存储上运行索引压缩。如果未设置，则将在包含 boltdb-shipper 或 tsdb 索引的所有对象存储上执行压缩。

• 用于管理删除请求的存储
• 新的配置选项 -boltdb.shipper.compactor.delete-request-store 决定删除请求应存储的位置。这个新选项优先于 -boltdb.shipper.compactor.shared-store。

在这些选项均未设置的情况下，将使用包含 tsdb 或 boltdb-shipper 索引的最新 period_config 中配置的 object_store 来存储删除请求，以确保待处理请求得到处理。

logfmt 解析器非严格解析

logfmt 解析器现在执行非严格解析，有助于扫描半结构化日志行。它跳过无效令牌，并尝试从日志行的其余部分提取尽可能多的键/值对。如果您依赖严格解析，并且期望解析器抛出错误，请使用 | logfmt --strict 启用严格模式。

logfmt 解析器不再将独立键（没有值的键）包含在结果标签集中。您可以使用 --keep-empty 标志来保留它们。

Jsonnet 2..9.0

已弃用的 PodDisruptionBudget 定义已移除

自 Kubernetes v1.25 起，不再提供 PodDisruptionBudget 的 policy/v1beta1 API 版本。为了支持最新版本的 Kubernetes，需要将 policy/v1beta1 替换为自 v1.21 起可用的新定义 policy/v1。

如果您使用 Kubernetes v1.21 或更高版本，则不会受到影响。

更多详情请参考官方迁移指南。

logfmt 解析器不再在结果标签集中包含独立键（没有值的键）。您可以使用 --keep-empty 标志来保留它们。

Jsonnet 2..9.0

已移除弃用的 PodDisruptionBudget 定义

从 Kubernetes v1.25 起，PodDisruptionBudget 的 policy/v1beta1 API 版本不再提供服务。为了支持最新版本的 Kubernetes，有必要将 policy/v1beta1 替换为自 v1.21 起可用的新定义 policy/v1。

如果您使用 Kubernetes v1.21 或更高版本，预计不会有影响。

请参考 官方迁移指南 了解更多详情。

2.8.0

Loki 2.8.0

LogQL 行为变更

当日志行中存在重复标签时，仅保留第一个值。之前仅保留最后一个值。

默认 retention_period 已更改

如果您满足以下条件，此更改将影响您

yaml 复制

compactor:
  retention_enabled: true

并且没有在 limits_config 中定义 retention_period，因此依赖之前的默认值 744h

在此版本中，默认值已更改为 0s。

值 0s 等同于“永久保留”或“禁用保留”。

如果您并且仅当您希望保留之前默认的 744h 时，请应用此配置。

yaml 复制

limits_config:
  retention_period: 744h

metrics.go 日志行中的 subqueries 替换为 splits 和 shards

为每个查询发出的 metrics.go 日志行中有一个名为 subqueries 的条目，旨在表示查询执行时的并行度。

目前它仅显示使用 Loki 按时间分割逻辑生成的子查询数量，不包括分片数量。

没有一种清晰的方法可以更新 subqueries 以包含分片信息，并且了解按时间分割与按分片因子生成的子查询之间的差异很有价值，特别是现在 TSDB 可以进行动态分片。

在 2.8 版本中，metrics.go 中不再包含 subqueries，它仍然存在于返回的统计信息 API 数据中，但仅为向后兼容，其值现在始终为零。

取而代之的是，您现在可以使用 splits 查看创建了多少按时间分割的间隔，并使用 shards 查看为查询创建的总分片数。

Promtail 2.8.0

引入了 Go 构建标签 promtail_journal_enabled

应传递 Go 构建标签 promtail_journal_enabled 以将 Journal 支持包含到 promtail 二进制文件中。如果您需要 Journal 支持，则需要使用标签 promtail_journal_enabled 运行 go build

shell 复制

go build --tags=promtail_journal_enabled ./clients/cmd/promtail

引入此标签旨在免除启用了 CGO 的 Linux/CentOS 用户在不需要 Journal 支持时安装 libsystemd-dev/systemd-devel 库。

Ruler

CLI 标志 ruler.wal-cleaer.period 已弃用

CLI 标志 ruler.wal-cleaer.period 现已弃用，并被修复拼写错误的 ruler.wal-cleaner.period 取代。yaml 配置保持不变

yaml 复制

ruler:
  wal_cleaner:
    period: 5s

Querier

query-frontend Kubernetes 无头服务更改为负载均衡服务

query-frontend Kubernetes 服务以前是无头的，用于两个目的

• 将 Loki 查询请求分发到所有可用的 Query Frontend Pod。
• 从 Queriers 发现 Query Frontend Pod 的 IP，以连接作为 worker。

这里的问题在于无头服务不支持负载均衡，并将负载均衡的任务留给客户端。此外，负载均衡服务不允许我们发现底层 Pod 的 IP。

为了满足这两个要求，我们进行了以下更改

• 将现有的 query-frontend Kubernetes 服务从无头改为负载均衡，以便在所有 Query Frontend 实例上实现公平的负载分发。
• 添加了 query-frontend-headless，用于从 queriers 发现 QF pod 的 IP，以连接作为 worker。

如果您通过将 query_scheduler_enabled 配置设为 true 来使用 Query Scheduler 部署 Loki，则此更改无需执行任何操作。如果您未使用 Query Scheduler，为了避免在 Read 路径上出现任何问题直到完全部署完成，最好按照以下步骤操作

• 只创建 query-frontend-headless 服务，不对 query-frontend 服务进行任何更改。
• 部署更改到 queriers。
• 部署其余的更改。

通用

存储和缓存统计信息

现在在 metrics.go 文件中记录统计信息，包括从存储下载 chunk 所需的时间，以及从缓存下载 chunk、进行索引查询和获取结果缓存响应所需的时间。

示例（注意 *_download_time 字段）

bash 复制

level=info ts=2022-12-20T15:27:54.858554127Z caller=metrics.go:147 component=frontend org_id=docker latency=fast query="sum(count_over_time({job=\"generated-logs\"}[1h]))" query_type=metric range_type=range length=6h17m48.865587821s start_delta=6h17m54.858533178s end_delta=5.99294552s step=1m30s duration=5.990829396s status=200 limit=30 returned_lines=0 throughput=123MB total_bytes=738MB total_entries=1 store_chunks_download_time=2.319297059s queue_time=2m21.476090991s subqueries=8 cache_chunk_req=81143 cache_chunk_hit=32390 cache_chunk_bytes_stored=1874098 cache_chunk_bytes_fetched=94289610 cache_chunk_download_time=56.96914ms cache_index_req=994 cache_index_hit=710 cache_index_download_time=1.587842ms cache_result_req=7 cache_result_hit=0 cache_result_download_time=380.555µs

使用 LogCLI 并带上 --stats 时也会显示这些统计信息。

2.7.0

Loki 2.7.0

Loki Canary 权限

Loki canary 的新 push 模式可以将 Loki canary 生成的日志直接推送到指定的 Loki URL。以前，它只写入本地文件，您需要一些代理（例如 promtail）来抓取并将其推送到 Loki。因此，如果您通过具有不同读写 Loki 授权策略的代理运行 Loki，那么我们传递给 Loki canary 的 auth 凭据现在需要同时具有 READ 和 WRITE 权限。

engine.timeout 和 querier.query_timeout 已弃用

以前，我们有两个配置用于定义查询超时：engine.timeout 和 querier.query-timeout。由于它们存在冲突，并且 engine.timeout 不如 querier.query-timeout 表达力强，我们将其弃用并移至 Limits Config 的 limits_config.query_timeout，默认值保持不变。

fifocache 已重命名

内存中的 fifocache 已重命名为 embedded-cache。这使得我们将来可以用其他实现（目前是简单的 FIFO 数据结构）来替换它，而不会引起混淆

将用于 chunks 的 Memcached Pod 均匀分布在 Kubernetes 节点上

我们现在将 memcached_chunks pod 均匀分布在可用的 Kubernetes 节点上，但允许在同一节点上调度多个 Pod。如果您希望每个节点最多只运行一个 Pod，请将 $.memcached.memcached_chunks.use_topology_spread 设置为 false。

虽然我们尝试使用 topology_spread_max_skew: 1 字段在每个 Kubernetes 节点上最多调度 1 个 memcached_chunks pod，但如果没有更多节点可用，则会在同一节点上调度多个 Pod。这可能会影响服务的可靠性，因此请根据您的风险承受能力调整这些值。

将 distributors 均匀分布在 Kubernetes 节点上

我们现在将 distributors 均匀分布在可用的 Kubernetes 节点上，但允许在同一节点上调度多个 distributor。如果您希望每个节点最多只运行一个 distributor，请将 $._config.distributors.use_topology_spread 设置为 false。

虽然我们尝试使用 topology_spread_max_skew: 1 字段在每个 Kubernetes 节点上最多调度 1 个 distributor，但如果没有更多节点可用，则会在同一节点上调度多个 distributor。这可能会影响服务的可靠性，因此请根据您的风险承受能力调整这些值。

将 queriers 均匀分布在 Kubernetes 节点上

我们现在将 queriers 均匀分布在可用的 Kubernetes 节点上，但允许在同一节点上调度多个 querier。如果您希望每个节点最多只运行一个 querier，请将 $._config.querier.use_topology_spread 设置为 false。

虽然我们尝试使用 topology_spread_max_skew: 1 字段在每个 Kubernetes 节点上最多调度 1 个 querier，但如果没有更多节点可用，则会在同一节点上调度多个 querier。这可能会影响服务的可靠性，因此请根据您的风险承受能力调整这些值。

server.http-listen-port 的默认值已更改

此值现在默认为 3100，因此 Loki 进程不再需要特殊权限。以前，它被设置为端口 80，这是一个特权端口。如果您需要 Loki 监听端口 80，可以使用 -server.http-listen-port=80 将其设置回以前的默认值。

docker-compose 配置已更新

docker-compose 配置 已更新到 v2.6.0 并包含许多改进。

主要变化包括

• 默认情况下，身份验证（多租户）是 启用 的；您可以通过在 production/docker/config/loki.yaml 中将 auth_enabled: false 来禁用它
• 存储现在使用 Minio 而不是本地文件系统
  • 将您当前的存储移到 .data/minio 中，它应该可以透明地工作
• log-generator 已添加 - 如果您不需要它，只需从 docker-compose.yaml 中移除该服务或不启动该服务即可

删除的配置已更改

compactor 配置中的全局 deletion_mode 选项已移至运行时配置。

• 需要从您的 compactor 配置中移除 deletion_mode 选项
• 需要将 deletion_mode 全局覆盖设置为所需的模式：disabled, filter-only, 或 filter-and-delete。默认情况下，启用 filter-and-delete。
• 需要移除任何按租户的 allow_delete 覆盖，或将其更改为带有所需模式的 deletion_mode 覆盖。

loki_log_messages_total 的指标名称已更改

此指标的名称已更改为 loki_internal_log_messages_total 以减少歧义。先前的名称仍然存在但已弃用。

使用报告 / 遥测配置名称已更改

向 Grafana 报告匿名使用统计信息的配置已从 usage_report 更改为 analytics。

TLS cipher_suites 和 tls_min_version 已移动

以前，这些配置项分别在 server.http_tls_config 和 server.grpc_tls_config 下进行配置。现在它们在 server.tls_cipher_suites 和 server.tls_min_version 下。这些值现在也可以为单个客户端进行配置，例如：distributor.ring.etcd 或 querier.ingester_client.grpc_client_config。

ruler.storage.configdb 已移除

早在 2.0 版本中，ConfigDB 已被禁止作为 Ruler 的存储选项。现在终于移除了相关的配置结构。

ruler.remote_write.client 已移除

不再能为 ruler 指定远程写客户端。

Promtail 2.7.0

gcp_push_target_parsing_errors_total 有一个新的 reason 标签

gcp_push_target_parsing_errors_total GCP Push Target 指标已添加一个名为 reason 的新标签。这包含了可能导致解析失败的详细信息。

Windows 事件日志：现在正确包含 user_data

在以前的版本中，user_data 字段的内容被错误地设置为与 event_data 相同的值。此问题已在 #7461 中修复，并且依赖于此错误行为的日志查询可能会受到影响。

2.6.0

Loki 2.6.0

非包装 rate 聚合的实现已更改

rate() 聚合函数的实现已回退到 #5013 之前的实现。这意味着每秒的速率是基于提取值的总和计算的，而不是基于随时间变化的平均增长。

如果您希望将提取的值视为 Counter 指标，您应该使用新的 rate_counter() 聚合函数，该函数计算向量每秒的平均增长率。

azure.container-name 的默认值已更改

此值现在默认为 loki，以前设置为 cortex。如果您依赖此容器名称作为 chunks 或 ruler 存储，则必须手动指定 -azure.container-name=cortex 或 -ruler.storage.azure.container-name=cortex。

2.5.0

Loki 2.5.0

split_queries_by_interval yaml 配置已移动

以前可以在两个地方定义此值

yaml 复制

query_range:
  split_queries_by_interval: 10m

和/或

yaml 复制

limits_config:
  split_queries_by_interval: 10m

在 2.5.0 版本中，它只能在 limits_config 部分定义，如果您不从 query_range 部分移除 split_queries_by_interval 配置，Loki 将无法启动。

此外，它的新默认值为 30m，而不是 0。

CLI 标志没有改变，仍然是 querier.split-queries-by-interval。

停止支持旧的 Prometheus 规则配置格式

以前可以以两种格式指定警报规则：1.x 格式（内部命名为 v0 的旧格式）和 2.x 格式。我们决定停止支持 1.x 格式，因为它相当旧，并且保持对其的支持需要大量代码。

如果您仍在使用旧格式，请查看 Alerting Rules 了解如何在新的格式中编写警报规则的说明。

作为参考，新格式的结构与以下类似

yaml 复制

 groups:
 - name: example
   rules:
   - alert: HighErrorRate
     expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
     for: 10m
     labels:
       severity: page
     annotations:
       summary: High request latency

同时，旧格式是一个具有以下格式的字符串

复制

 ALERT <alert name>
   IF <expression>
   [ FOR <duration> ]
   [ LABELS <label set> ]
   [ ANNOTATIONS <label set> ]

默认配置值的更改

• parallelize_shardable_queries 在 query_range 配置下，现在默认值为 true。
• split_queries_by_interval 在 limits_config 配置下，现在默认值为 30m，以前是 0s。
• max_chunk_age 在 ingester 配置中，现在默认值为 2h，以前是 1h。
• query_ingesters_within 在 querier 配置下，现在默认值为 3h，以前是 0s。结束时间超过 3h 前的任何查询（或子查询）都不会发送给 ingesters，这为 ingesters 节省了处理通常不包含的数据的工作。如果您定期向 Loki 写入旧数据，您可能需要将此值改回 0s 以始终查询 ingesters。
• max_concurrent 在 querier 配置下，现在默认值为 10，而不是 20。
• match_max_concurrent 在 frontend_worker 配置下，现在默认值为 true，这取代了 parallelism 设置，该设置现在可以从您的配置中移除。现在可以通过 querier 的 max_concurrent 设置来控制单个进程的查询并行度。
• flush_op_timeout 在 ingester 配置块下，现在默认值为 10m，从 10s 增加。这有助于在 Loki 启动时重放大型 WAL，并避免 msg="failed to flush" ... context deadline exceeded 错误。

Promtail 2.5.0

gcplog 标签已更改

• 资源标签已从 __<NAME> 移至 __gcp_resource_labels_<NAME>，例如，如果您之前使用了 __project_id，则需要更新您的 relabel 配置以使用 __gcp_resource_labels_project_id。
• resource_type 已移至 __gcp_resource_type

promtail_log_entries_bytes_bucket 直方图已移除

这个直方图按文件报告日志行大小的分布。它为每个被 tail 的文件有 8 个桶。

这会产生大量序列，我们认为这个指标的价值不足以抵消生成的序列数量，因此我们将其移除。

虽然这不是直接替代，但我们发现更有用的两个指标是大小和行计数器，可通过 pipeline stages 配置，关于如何配置这些指标的示例可以在 metrics pipeline stage docs 文档中找到。

added Docker target 日志消息级别已从 error 降级为 info

如果您的仪表板依赖于日志级别，请更改它们以搜索 msg="added Docker target" 属性。

Jsonnet 2.5.0

定义为命令行参数的 Compactor 配置已移至 yaml 配置

以下 2 个在 jsonnet 中定义为命令行参数的 compactor 配置现已移至 yaml 配置

yaml 复制

# Directory where files can be downloaded for compaction.
# CLI flag: -boltdb.shipper.compactor.working-directory
[working_directory: <string>]

# The shared store used for storing boltdb files.
# Supported types: gcs, s3, azure, swift, cos, filesystem.
# CLI flag: -boltdb.shipper.compactor.shared-store
[shared_store: <string>]

2.4.0

以下是重要的更改，在升级 Loki 之前应进行审阅和理解。

Loki 2.4.0

以下更改与升级 Loki 有关。

单个二进制文件不再运行 table-manager

单个二进制 Loki 指的是使用 -target=all 运行 loki，这是未传递 -target 标志时的默认设置。

这将影响以下情况下的任何人

1. 运行使用除 boltdb-shipper 或 boltdb 以外的任何索引类型的单个二进制 Loki
2. 依赖于使用 retention_deletes_enabled 和 retention_period 配置的保留功能

处于情况 #1 且未使用 boltdb-shipper 或 boltdb（例如 cassandra 或 bigtable）的任何人，应修改其 Loki 命令以包含 -target=all,table-manager，这将指示 Loki 为您运行一个 table-manager。

处于情况 #2 的任何人，您有两种选择，第一种（不推荐）是通过添加 -target=all,table-manager 来运行带有 table-manager 的 Loki。

第二种也是推荐的解决方案是使用 compactor 进行删除

yaml 复制

compactor:
  retention_enabled: true
limits_config:
  retention_period: [30d]

请参阅 retention docs 文档了解更多信息。

启动时的日志消息：proto: 重复的 proto 类型已注册

PR #3842 cyriltovena：将 cortex chunk 存储分支到 Loki。

由于 Cortex 不再计划使用 chunk 包，我们决定将其分支到我们的存储包中，以便轻松演进和修改。然而，作为副作用，我们仍然 vendor Cortex，其中包含此分支代码和 protobuf 文件，导致启动时出现以下日志消息

bash 复制

2021-11-04 15:30:02.437911 I | proto: duplicate proto type registered: purgeplan.DeletePlan
2021-11-04 15:30:02.437936 I | proto: duplicate proto type registered: purgeplan.ChunksGroup
2021-11-04 15:30:02.437939 I | proto: duplicate proto type registered: purgeplan.ChunkDetails
...

这些消息是无害的，我们将在将来努力移除它们。

将一些默认限制更改为常用值

PR 4415 DylanGuedes：更改了一些限制的默认值，以保护用户免受因依赖默认配置而导致的过量摄取负载压垮其集群。

我们建议您仔细检查您的 Loki 配置中是否存在以下参数：ingestion_rate_strategy, max_global_streams_per_user max_query_length max_query_parallelism max_streams_per_user reject_old_samples reject_old_samples_max_age。如果它们不存在，我们建议您仔细检查新值是否会对您的系统产生负面影响。更改如下

配置默认值变更

• 当使用默认未启用的索引查询缓存时，chunk_retain_period 是必需的。如果您已配置 index_queries_cache_config 部分，请确保将 chunk_retain_period 设置得大于您的缓存 TTL。
• chunk_idle_period 是一个 chunk 在未接收到任何日志之前被 flush 的等待时长。
• chunk_target_size 已增加，以便 flush 稍大的 chunk。如果使用 memcache 作为 chunks 存储，请确保它能接受最大 1.5MB 大小的文件。

默认启用内存中 FIFO 缓存

Loki 现在默认在内存中启用了结果缓存和 chunk 缓存以提高性能。但这可能会增加内存使用量，因为默认情况下缓存被允许占用高达 1GB 的内存。

如果您想禁用这些缓存或更改此内存限制

禁用

yaml 复制

chunk_store_config:
  chunk_cache_config:
    enable_fifocache: false
query_range:
  results_cache:
    cache:
      enable_fifocache: false

调整大小

yaml 复制

chunk_store_config:
  chunk_cache_config:
    enable_fifocache: true
    fifocache:
      max_size_bytes: 500MB
query_range:
  results_cache:
    cache:
      enable_fifocache: true
      fifocache:
        max_size_bytes: 500MB

Ingester Lifecycler 的 final_sleep 现在默认为 0s

• 4608 **trevorwhitney**: 将 ingester lifecycler 的 final_sleep 默认值从 30s 更改为 0s

这个最后的睡眠是为了让 Loki 在关闭前运行足够长的时间以进行最后一次 Prometheus scrape，但它也导致 Loki 在关闭时闲置 30 秒，这对许多人来说是令人恼火的体验。

我们认为默认情况下禁用这种睡眠行为会更好，但任何人都可以直接设置此配置变量以恢复到以前的行为。

Ingester WAL 现在默认开启，chunk transfer 默认禁用

• 4543 **trevorwhitney**: 更改更多默认值并改进通用存储配置的应用
• 4629 **owen-d**: 在 Loki jsonnet 库中默认启用 WAL
• 4624 **chaudum**: 在 jsonnet 库中禁用 chunk transfers

这更改了一些默认值，导致 ingester WAL 现在默认开启，并且 chunk transfer 重试默认禁用。请注意，这意味着 Loki 现在默认依赖本地磁盘作为其 WAL (write ahead log) 目录。该目录默认为 wal，但可以通过 --ingester.wal-dir 或通用配置部分的 path_prefix 进行覆盖。以下是包含先前默认值和新值的配置片段。

先前默认值

yaml 复制

ingester:
  max_transfer_retries: 10
  wal:
    enabled: false

新默认值

yaml 复制

ingester:
  max_transfer_retries: 0
  wal:
    enabled: true

推荐使用预写日志 (WAL)，现在也是默认设置。但是，使用 WAL 与 chunk transfers 不兼容，如果您已将 ingester.max-transfer-retries 显式配置为非零值，则必须将其设置为 0 以禁用 transfer。

Memberlist 配置现在自动应用于所有未配置的环

• 4400 **trevorwhitney**: 配置：提供 memberlist 配置时自动应用于所有环

此更改影响 ingester、distributor 和 ruler 环的行为。以前，如果您想为所有这些环使用 memberlist，您必须提供 memberlist 配置，并为每个您想要使用 memberlist 的环的 kvstore 指定 store: memberlist。例如，您的配置可能看起来像这样：

yaml 复制

memberlist:
  join_members:
    - loki.namespace.svc.cluster.local
distributor:
  ring:
    kvstore:
      store: memberlist
ingester:
    lifecycler:
      ring:
        kvstore:
          store: memberlist
ruler:
  ring:
    kvstore:
      store: memberlist

现在，如果您提供了包含至少一个 join_members 的 memberlist 配置，Loki 会将所有环默认使用类型为 memberlist 的 kvstore。您可以通过覆盖特定配置来更改此行为。例如，如果您想为 ruler 环使用 consul，但为 ingester 和 distributor 使用 memberlist，您可以使用以下配置（尽管我们不知道为什么有人会这样做）：

yaml 复制

memberlist:
  join_members:
    - loki.namespace.svc.cluster.local
ruler:
  ring:
    kvstore:
      store: consul
      consul:
        host: consul.namespace.svc.cluster.local:8500

更改了一些 GRPC 服务器设置的默认值

• 4435 **trevorwhitney**: 更改两个 GRPC 设置的默认值，以便 querier 可以连接到 frontend/scheduler

这更改了 GRPC 服务器使用的两个默认值：grpc_server_min_time_between_pings 和 grpc_server_ping_without_stream_allowed。

先前值:

yaml 复制

server:
  grpc_server_min_time_between_pings: '5m'
  grpc_server_ping_without_stream_allowed: false

新值:

yaml 复制

server:
  grpc_server_min_time_between_pings: '10s'
  grpc_server_ping_without_stream_allowed: true

关于此更改的更多信息请参见此问题。

部分指标前缀已从 cortex_ 更改为 loki_

• #3842/ #4253 **jordanrushing**: 与 chunk storage 和 runtime config 相关的指标前缀已从 cortex_ 更改为 loki_。

yaml 复制

cortex_runtime_config* -> loki_runtime_config*
cortex_chunks_store* -> loki_chunks_store*

记录规则存储现在具有持久性

• 4344 **dannykopping**: 按租户的 WAL

以前，recording rules 生成的 samples 只会在内存中缓冲，然后远程写入 Prometheus；从这个版本开始，ruler 现在将这些 samples 写入按租户的 Write-Ahead Log 以实现持久性。有关按租户的 WAL 的更多详细信息可以在此处找到。

ruler 现在需要持久存储 - 有关部署的更多详细信息，请参阅操作页面。

Promtail 2.4.0

以下更改与升级 Promtail 有关。

Promtail 在 scrape gcplog 目标时不再插入 promtail_instance 标签

• 4556 **james-callahan**: 移除 Promtail 在 scrape gcplog 目标时添加的 promtail_instance 标签。

2.3.0

Loki 2.3.0

对不包含至少一个等值匹配器的查询引入了限制

PR 3216 **sandeepsukhani**: 检查 stream selectors 是否至少有一个等值匹配器

此更改现在会拒绝任何不包含至少一个等值匹配器的查询，以下示例可以更好地说明：

{namespace=~".*"}

此查询现在将被拒绝，但有几种方法可以修改它使其成功：

添加至少一个等值标签匹配器

{cluster="us-east-1",namespace=~".*"}

使用 .+ 代替 .*

{namespace=~".+"}

这种差异可能看起来很微妙，但分解来看，. 匹配任何字符，* 匹配前一个字符零次或多次，而 + 匹配前一个字符一次或多次。.* 的情况会匹配空值，而 .+ 不会，这是重要的区别。{namespace=""} 是一个无效的请求（除非您像上面的示例那样添加另一个等值标签匹配器）。

此更改的原因与 Loki 中索引查找的工作方式有关，如果您没有至少一个等值匹配器，Loki 必须执行完整的索引表扫描，这是一项昂贵且缓慢的操作。

2.2.0

Loki 2.2.0

在升级到 2.2 之前，务必先升级到 2.0 或 2.1

在 Loki 2.2 中，我们将 chunk 格式的内部版本从 v2 更改为 v3，这是一个透明的更改，仅在您尝试_降级_ Loki 安装时才相关。我们在 2.0.1 和 2.1 以及 2.2 和任何未来版本中都包含了读取 v3 chunks 的代码。

如果您升级到 2.2+，创建的任何 chunks 只能由 2.0.1、2.1 和 2.2+ 读取。

这使得在升级到 2.2 **之前**，首先升级到 2.0、2.0.1 或 2.1 变得很重要，这样如果您因任何原因需要回滚，可以轻松完成。

Loki 配置

如果您使用 query-frontend 并设置了 sharded_queries_enabled: true，请阅读此部分

我们发现，在长时程范围内的 sharded queries 相关查询调度可能导致单个查询在按租户的工作队列中出现不公平的工作调度。

max_query_parallelism 设置旨在限制单个查询允许同时放入按租户工作队列中的 split 和 sharded 的“工作”单元数量。以前的行为是使用 split_queries_by_interval 按时间分割查询，并在填充队列时将此值与 max_query_parallelism 进行比较，但在启用 sharding 的情况下，在应用 max_query_parallelism 限制后，每个 split 都会被进一步 sharded 为 16 个额外的工作单元。

在 2.2 中，我们更改了此行为，在对查询进行 splitting _和_ sharding 后应用 max_query_parallelism，从而实现了每个查询更公平、更符合预期的队列调度。

**这意味着** 如果您使用 query frontend 并启用了 sharding_queries_enabled（您应该这样做），Loki 将为每个查询放入工作队列的工作量大大减少。**如果您注意到查询性能变慢，您可能需要增加 max_query_parallelism 设置**。实际上，除非您的集群中有**大量** querier 或 querier 的 parallelism frontend_worker 设置非常高，否则您可能不会看到差异。

您可以考虑将当前 max_query_parallelism 设置乘以 16 以获得以前的行为，尽管实际上我们认为除非您有一个庞大的 querier worker 池，否则很少有人会真正想要这么高的值。

另请注意，务必确保 max_outstanding_per_tenant 始终大于 max_query_parallelism，否则大型查询会自动失败并向用户返回 429 错误。

Promtail 2.2.0

在 2.0 版本中，我们删除了 Promtail 配置中长期被弃用的 entry_parser 配置，但这样做引入了一个非常令人困惑和错误的默认行为。

如果您没有指定 pipeline_stages 条目，您将获得一个包含 docker pipeline stage 的默认配置。这可能会导致一些非常令人困惑的结果。

在 3404 中，我们纠正了此行为。

**如果您正在使用 docker，并且您的任何 scrape_configs 缺少 pipeline_stages 定义**，您应该添加以下内容以获得正确行为：

yaml 复制

pipeline_stages:
  - docker: {}

2.1.0

从 2.0.0 升级到 2.1.0 应该相当顺利，请注意以下两点：

Helm charts 已迁移

Helm charts 现在位于Grafana Helm charts 仓库中。

Helm 仓库 URL 现在是：https://grafana.github.io/helm-charts。

Fluent Bit 插件已重命名

Fluent Bit 现在官方支持 Loki 作为输出插件。

然而，这与我们现有的输出插件产生了命名冲突（新的原生输出使用了名称 loki），因此我们重命名了我们的插件。

随着时间的推移，我们的计划是弃用并移除我们的输出插件，转而支持原生的 Loki。但在那之前，您可以通过以下更改继续使用该插件：

旧

shell 复制

[Output]
    Name loki

新

shell 复制

[Output]
    Name grafana-loki

2.0.0

这是一个主要的 Loki 版本，有一些非常重要的升级注意事项。但总体来说，影响较大的更改非常少，对于大多数人来说，这将是一个无缝升级。

2.0.0 升级主题

• 重要 如果您正在使用 docker 镜像，请阅读此内容！
• 重要 boltdb-shipper 升级注意事项
• 重要 results_cachemax_freshness 已从 yaml 配置中移除
• Promtail 移除了 entry_parser 配置
• 如果您想使用新的 single store index 和 v11 schema

重要 如果您正在使用 docker 镜像，请阅读此内容！

（包括 Helm、Tanka、docker-compose 等）

docker 镜像中的默认配置文件、Helm 的默认 values.yaml 以及 Tanka 的 jsonnet 都指定了 schema 定义，以便更容易开始使用。

在 2.0 中，默认值现在是 v11 schema 和 boltdb-shipper 索引类型。

如果您使用的索引类型是 aws、bigtable 或 cassandra，这意味着您已经定义了自定义 schema，关于 schema **无需**进一步操作。但是，如果您想放弃这些独立的索引存储并仅使用一个对象存储，可以考虑添加新的 schema 条目来使用新的 boltdb-shipper 类型。

应对措施

所需的最低限度操作是创建一个配置文件，其中指定的 schema 与先前的默认设置一致。

（请记住，这只会告诉 Loki 使用旧的 schema 默认值。如果您想升级到 v11 和/或迁移到 single store boltdb-shipper，请参见下文）

我们在三个地方硬编码了 schema 定义：

Helm

Helm 在 values.yaml 文件中包含相同的内部 schema 已有很长时间了。

如果您提供自己的 values.yaml 文件，则**无需**任何操作，因为您已经有了 schema 定义。

如果您没有提供自己的 values.yaml 文件，您需要创建一个！

我们建议使用包含的来自 1.6.0 标签的 values.yaml 文件。

这与 2.0 之前默认 values.yaml 文件中的内容一致，并且是 Loki 在 2.0 后正常工作所必需的。

如上所述，您还应该考虑迁移到 v11 schema 和 boltdb-shipper，更多信息请参见下文。

Tanka

这可能只影响一小部分 Tanka 用户，因为 Loki 的默认 schema 配置强制使用了 GCS 和 bigtable。

如果您的 main.jsonnet（或手动创建的 jsonnet 中的其他位置）没有 schema 配置部分，则需要添加一个，如下所示：

jsonnet 复制

{
  _config+:: {
    using_boltdb_shipper: false,
    loki+: {
      schema_config+: {
        configs: [{
          from: '2018-04-15',
          store: 'bigtable',
          object_store: 'gcs',
          schema: 'v11',
          index: {
            prefix: '%s_index_' % $._config.table_prefix,
            period: '168h',
          },
        }],
      },
    },
  }
}

将 jsonnet 配置更改为使用 boltdb-shipper 类型与下文相同，您需要添加一个新的 schema 部分。

**然而** 请注意，当您更改 using_boltdb_shipper: true 时，ingesters 和 queriers 的部署类型将更改为 StatefulSets！使用 boltdb-shipper 的 ingester 和 querier 需要 StatefulSets。

Docker（例如 docker-compose）

对于与 docker 相关的情况，您必须挂载一个与容器内部捆绑文件分开的 Loki 配置文件。

我建议从github 上的 1.6.0 tag 获取先前的默认文件。

如何将其挂载并供 Loki 使用可能会因您使用镜像的方式而异，但这是一个常见示例：

shell 复制

docker run -d --name=loki --mount type=bind,source="path to loki-config.yaml",target=/etc/loki/local-config.yaml

Loki docker 镜像期望在 /etc/loki/local-config.yaml 找到配置文件。

重要：boltdb-shipper 升级注意事项

boltdb-shipper 索引类型在 1.6.0 和 2.0.0 之间发生了重大变化，如果您已在运行此索引并正在升级，则需要格外小心。

对您的对象存储中的 index 目录进行完整备份，该位置可能会因您使用的存储而略有不同。它应该是一个名为 index 的文件夹，里面包含许多名为 index_18561、index_18560... 的文件夹。

chunks 目录不需要任何特殊备份。

如果您有测试环境，请在升级关键数据之前进行测试。

有 2 个重大变化需要备份此数据，因为它们将使回滚成为不可能：

• 包含了一个 compactor，它将把现有的索引文件压缩到每天一个，并删除未压缩的文件。
• 所有索引文件在上传前现在都已 gzipped。

第二部分很重要，因为 1.6.0 不知道如何读取 gzipped 文件，因此任何新上传的文件或任何压缩过的文件都将对 1.6.0 或更早版本不可读。

**尽管如此**，我们不预期会有问题，我们目前的测试没有发现任何问题，但一些额外的预防措施可能会在不可预见的情况下避免数据丢失！

通过 GitHub issues 报告任何问题，或在 #loki slack 频道与我们联系。

在 2.0 中使用 boltdb-shipper 需要共享存储（S3、GCS 等），使用 ring 在 HA 中运行独立文件系统存储的模式未获得官方支持。

我们没有明确限制此功能，但我们没有时间对其进行实际测试，这就是为什么我们删除了文档并将其列为不受支持的原因。

如果以微服务模式运行，先部署 ingesters 再部署 queriers

当索引类型为 boltdb-shipper 时，ingesters 现在暴露了一个新的 RPC 方法供 queriers 使用。Queriers 通常比 ingesters 更快地 rollout，因此如果新的 queriers 使用新的 RPC 查询旧的 ingesters，查询将会失败。为避免升级期间的查询中断，请在 queriers 之前 rollout ingesters。

如果运行 compactor，请确保它对对象存储具有删除权限

compactor 是一个可选但建议的组件，用于合并和去重 boltdb-shipper 索引文件。在压缩索引文件时，compactor 会写入一个新文件并删除未优化的文件。确保 compactor 具有适当的文件删除权限，例如，对于 AWS S3，需要 s3:DeleteObject 权限。

重要：results_cache.max_freshness 已从 YAML 配置中移除

results_cache 中的 max_freshness 配置已被移除，取而代之的是 limits_config 中名为 max_cache_freshness_per_query 的另一个标志，其效果相同。如果您设置了 results_cache.max_freshness，请改用 limits_config.max_cache_freshness_per_query YAML 配置。

Promtail 配置已移除

Promtail 中长期被弃用的 entry_parser 配置已被移除，请改用pipeline_stages。

升级 schema 以使用 boltdb-shipper 和/或 v11 schema

如果您还想利用新的 Single Store (boltdb-shipper) 索引，以及您尚未使用 v11 schema。

您可以通过添加新的 schema 条目来做到这一点。

这是一个例子：

yaml 复制

schema_config:
  configs:
    - from: 2018-04-15           ①
      store: boltdb              ①④
      object_store: filesystem   ①④
      schema: v11                ②
      index:
        prefix: index_           ①
        period: 168h             ①
    - from: 2020-10-24           ③
      store: boltdb-shipper
      object_store: filesystem   ④
      schema: v11
      index:
        prefix: index_
        period: 24h              ⑤

① 确保所有这些与您当前的 schema 配置匹配 ② 确保这与您先前的 schema 版本匹配，例如 Helm 很可能是 v9 ③ 确保这是一个**未来**日期，请记住 Loki 只知道 UTC，所以确保是未来的 UTC 日期 ④ 确保这与您现有的配置匹配（例如，您可能正在使用 gcs 作为您的 object_store）⑤ boltdb-shipper 需要 24h

存储说明页面上有更多示例，包括设置 boltdb-shipper 的 storage 部分所需的信息。

1.6.0

重要：Ksonnet 端口已更改，并从 Docker 镜像中移除了 NET_BIND_SERVICE capability

在 1.5.0 中，我们将 Loki 用户更改为不以 root 身份运行，这导致绑定到端口 80 时出现问题。为了解决这个问题，我们更新了 docker 镜像，为 loki 进程添加了 NET_BIND_SERVICE capability，这使得 Loki 能够以非 root 用户身份绑定到端口 80，只要底层系统允许该 Linux capability。

出于多种原因，这已被证明是一个问题，并且在 PR 2294 中，该 capability 已被移除。

现在，使用发布的 docker 镜像启动 Loki 时，不再可能使用小于 1024 的端口。

Helm 的默认端口一直是 3100，Helm 用户应该不会受到影响，除非他们更改了默认设置。

然而，Ksonnet 用户应仔细检查其配置，在 PR 2294 中，loki 端口已从 80 更改为 3100。

重要：如果您在微服务模式下运行 Loki，请遵循特殊的 rollout 指令

已添加新的 ingester GRPC API，可以加快指标查询。为了确保 rollout 期间没有查询错误，**请务必先升级所有 ingesters。**完成后，您可以继续进行其余的部署，这是为了确保 queriers 不会查找尚未可用的 API。

如果您一次性 rollout 所有组件，具有新代码的 queriers 将尝试查询 API 上可能没有新方法的 ingesters，查询将会失败。

这只会影响读取（查询），不影响写入，并且仅在 rollout 期间发生。

重要：Helm 和 Ksonnet 的 scrape 配置更改将影响 Promtail 创建的标签

Loki PR 2091 对 Promtail scrape 配置进行了几项更改。

这是由 jsonnet-libs PR 261 触发的。

上述 PR 将 instance 标签更改为在 scrape config 中真正唯一。它还添加了 pod 和 container target label，以便指标可以轻松地与来自 cAdvisor、KSM 和 Kubelet 的指标关联起来。

此提交也对 Loki scrape config 进行了相同的更改。它还移除了 container_name 标签。它与 container 标签相同，并且先前已添加到 Loki 中。但是，container_name 标签已被弃用，并在 Kubernetes 1.16 中消失，因此很快将无法用于直接关联。

总结

Helm 和 Ksonnet 的 Promtail scrape config 中更改了以下标签：

instance -> pod container_name -> container

实验性 boltdb-shipper 更改

PR 2166 现在强制索引周期必须精确为 24h。

如果 active schema 或 upcoming schema 未设置为 24h 的周期，Loki 将启动失败并报错。

您可以添加一个新的 schema 配置，如下所示：

yaml 复制

schema_config:
  configs:
    - from: 2020-01-01      <----- This is your current entry, date will be different
      store: boltdb-shipper
      object_store: aws
      schema: v11
      index:
        prefix: index_
        period: 168h
    - from: [INSERT FUTURE DATE HERE]   <----- Add another entry, set a future date
      store: boltdb-shipper
      object_store: aws
      schema: v11
      index:
        prefix: index_
        period: 24h   <--- This must be 24h

如果您使用的不是 schema: v11，这也是在_新的 schema 配置中_进行更改的好机会。

boltdb-shipper 内部机制也进行了重大 overhaul，这对用户来说应该是不可见的，但由于此功能是实验性的且正在开发中，可能存在 bug！

如果您查看存储，最显著的变化是 Loki 不再更新现有文件，而是每 15 分钟创建一个新的索引文件。这是确保对象存储中的对象不可变的重要一步，将简化未来的压缩和删除等操作。

CLI 参数重大更改

以下 CLI 参数已更改以提高一致性，预计不会被广泛使用。

diff 复制

- querier.query_timeout
+ querier.query-timeout

- distributor.extra-query-delay
+ querier.extra-query-delay

- max-chunk-batch-size
+ store.max-chunk-batch-size

- ingester.concurrent-flushed
+ ingester.concurrent-flushes

Loki Canary 指标名称更改

在为 canary 添加新功能时，我们意识到现有指标不符合计数器名称的标准，以下指标已重命名：

nohighlight 复制

loki_canary_total_entries               ->      loki_canary_entries_total
loki_canary_out_of_order_entries        ->      loki_canary_out_of_order_entries_total
loki_canary_websocket_missing_entries   ->      loki_canary_websocket_missing_entries_total
loki_canary_missing_entries             ->      loki_canary_missing_entries_total
loki_canary_unexpected_entries          ->      loki_canary_unexpected_entries_total
loki_canary_duplicate_entries           ->      loki_canary_duplicate_entries_total
loki_canary_ws_reconnects               ->      loki_canary_ws_reconnects_total
loki_canary_response_latency            ->      loki_canary_response_latency_seconds

Ksonnet 更改

在 production/ksonnet/loki/config.libsonnet 中，变量 storage_backend 曾经的默认值为 'bigtable,gcs'。此设置已更改为不提供默认值，并且如果在您的环境 jsonnet 中未提供，将报错。这是一个示例，说明您应该添加什么以获得与默认设置相同的行为（namespace 和 cluster 应该已经定义）：

jsonnet 复制

_config+:: {
    namespace: 'loki-dev',
    cluster: 'us-central1',
    storage_backend: 'gcs,bigtable',

默认使用 gcs,bigtable 对于使用 Ksonnet 连接其他存储后端的用户来说是令人困惑的，因为它会表现为晦涩的 bigtable 错误。

1.5.0

配置重大更改

Loki 1.5.0 包含了 Cortex v1.0.0（恭喜！），它有大量的更改列表。

虽然命令行参数的更改也会影响 Loki，但我们通常建议使用配置文件。

Cortex 对配置文件进行了大量清理，强烈建议您在升级到 Loki 1.5.0 之前查看配置文件带注释的差异。

以下字段已从 YAML 配置中完全移除：claim_on_rollout（始终为 true），normalise_tokens（始终为 true）。

测试您的配置

要查看您的配置是否需要更改，一个快速测试方法是从发布页面下载 1.5.0（或更新版本）二进制文件。

然后运行二进制文件并提供您的配置文件 ./loki-linux-amd64 -config.file=myconfig.yaml

如果存在不再有效的配置，您将立即看到错误。

shell 复制

./loki-linux-amd64 -config.file=loki-local-config.yaml
failed parsing config: loki-local-config.yaml: yaml: unmarshal errors:
  line 35: field dynamodbconfig not found in type aws.StorageConfig

参考差异列表，我可以看到此配置已更改：

diff 复制

-  dynamodbconfig:
+  dynamodb:

此外，其他几个 AWS 相关配置也已更改，需要同时更新。

Loki Docker 镜像用户和文件位置更改

为了提高安全性，在 1.5.0 版本中，Docker 容器不再以 root 用户运行 loki 进程，而是以用户 loki（UID 10001，GID 10001）身份运行。

这可能会在几个方面影响用户：

Loki 端口

如果您运行的 Loki 配置打开的端口号大于 1024（默认是 HTTP 的 3100 和 GRPC 的 9095），则端口方面应该一切正常。

如果您运行的 Loki 配置打开的端口号小于 1024，Linux 通常需要 root 权限才能这样做，**但是**在 Docker 容器中，我们运行了 setcap cap_net_bind_service=+ep /usr/bin/loki。

此 capability 允许 loki 进程以非 root 用户身份运行时绑定到小于 1024 的端口。

然而，并非所有环境都允许此 capability，在 linux 中可能限制此 capability。如果存在此限制，您将被迫运行 Loki，其 HTTP 和 GRPC 端口必须大于 1024。

文件系统

在 1.4.0 及更早版本中，docker 容器中包含的配置文件使用的是以下目录：

shell 复制

/tmp/loki/index
/tmp/loki/chunks

在 1.5.0 中，这已更改：

shell 复制

/loki/index
/loki/chunks

这主要会影响使用 docker-compose 或 docker 运行 Loki 并指定卷来持久化存储的用户。

这里有两个需要关注的问题，一个是文件的正确所有权，另一个是确保您的挂载已更新到新位置。

一个可能的升级路径如下所示：

如果我使用此命令运行 Loki docker run -d --name=loki --mount source=loki-data,target=/tmp/loki -p 3100:3100 grafana/loki:1.4.0

这会将名为 loki-data 的 docker 卷挂载到 /tmp/loki 文件夹，这是 Loki 在 1.4.0 中持久化 index 和 chunks 文件夹的位置。

要迁移到 1.5.0，我可以执行以下操作（请注意，您的容器名称、路径、卷等可能不同）：

bash 复制

docker stop loki
docker rm loki
docker run --rm --name="loki-perm" -it --mount source=loki-data,target=/mnt ubuntu /bin/bash
cd /mnt
chown -R 10001:10001 ./*
exit
docker run -d --name=loki --mount source=loki-data,target=/loki -p 3100:3100 grafana/loki:1.5.0

请注意 1.5.0 中 target=/loki 更改为包含的 Loki 配置文件中指定的新数据目录位置。

如果您可以轻松访问这些文件并直接运行 chown 命令，则使用 ubuntu 镜像中间步骤来更改 Loki 文件的所有者到新用户可能不是必需的。也就是说，如果您可以访问 /var/lib/docker/volumes 或者您挂载到了不同的本地文件系统目录，您可以直接更改所有权而无需使用容器。

Loki Duration 配置

如果您收到如下错误：

nohighlight 复制

 ./loki-linux-amd64-1.5.0 -log.level=debug -config.file=/etc/loki/config.yml
failed parsing config: /etc/loki/config.yml: not a valid duration string: "0"

这是因为一些底层更改不再允许不带单位的时间段。

遗憾的是，yaml 解析器不会给出行号，但这很可能是以下两个之一：

yaml 复制

chunk_store_config:
  max_look_back_period: 0s # DURATION VALUES MUST HAVE A UNIT EVEN IF THEY ARE ZERO

table_manager:
  retention_deletes_enabled: false
  retention_period: 0s # DURATION VALUES MUST HAVE A UNIT EVEN IF THEY ARE ZERO

Promtail 配置更改

Promtail 中使用的底层退避库有一个配置更改，该更改最初未在发布说明中提及。

如果您收到此错误：

nohighlight 复制

Unable to parse config: /etc/promtail/promtail.yaml: yaml: unmarshal errors:
  line 3: field maxbackoff not found in type util.BackoffConfig
  line 4: field maxretries not found in type util.BackoffConfig
  line 5: field minbackoff not found in type util.BackoffConfig

新值为：

yaml 复制

min_period:
max_period:
max_retries:

1.4.0

Loki 1.4.0 包含了 Cortex v0.7.0-rc.0，其中包含几个破坏性配置更改。

在cache_config中，defaul_validity 已更改为 default_validity。

如果您通过参数而不是配置文件配置了 schema，则不再支持此方式。这不是我们曾通过文档提供的一个选项，也不太可能有人这样做，但值得一提。

其他配置更改应该与 Loki 无关。

必需的升级路径

新包含的 Cortex 版本移除了 ring 中与 de-normalized tokens 相关的代码。您需要知道的是：

下面提到的“共享环”是指在以下配置中使用 _consul_ 或 _etcd_ 作为值：

yaml 复制

kvstore:
  # The backend storage to use for the ring. Supported values are
  # consul, etcd, inmemory
  store: <string>

• 未使用共享环（内存中）运行：无需操作
• 使用共享环运行并从 v1.3.0 升级到 v1.4.0：无需操作
• 使用共享环运行并从任何低于 v1.3.0 的版本（例如 v1.2.0）升级到 v1.4.0：**需要操作**

如果您未处于 1.3.0 版本且正在使用共享环，则有两种升级选项：

• 在升级到 v1.4.0 **之前**先升级到 v1.3.0

或者

• 如果您正在运行单个二进制文件，只需将此标志添加到您的单个二进制文件命令中即可。

1. 将以下配置添加到您的 ingesters 命令中：-ingester.normalise-tokens=true
2. 使用此配置重启您的 ingesters
3. 继续升级到 v1.4.0
4. 移除配置选项（仅在所有组件都运行 v1.4.0 后执行此操作）

也可以通过配置文件启用此标志，请参阅lifecycler_config 配置选项。

如果使用 Helm Loki chart

yaml 复制

extraArgs:
  ingester.normalise-tokens: true

如果使用 Helm Loki-Stack chart

yaml 复制

loki:
  extraArgs:
    ingester.normalise-tokens: true

可能出现的问题

如果您尝试将 v1.4.0 ingester 添加到由 Loki v1.2.0 或更早版本创建且没有命令行参数 -ingester.normalise-tokens=true（或通过配置文件配置）的 ring 中，v1.4.0 ingester 将移除 ring 中所有其他 ingester 的所有条目，因为它无法“看到”它们。

这将导致 distributors 写入失败，并导致系统整体摄取失败。

如果发生这种情况，您需要立即回滚您的部署。您需要尽快从 ring 中移除 v1.4.0 ingester，这应该允许现有 ingesters 重新插入它们的 tokens。您还需要移除任何 v1.4.0 distributors，因为它们也无法理解旧的 ring，并且将无法发送流量。