Grafana Loki 日志条目删除Log Entry Deletion完整指南配置、API 与底层原理【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiGrafana Loki 支持按流stream、按时间窗口、按可选行过滤器删除日志条目该能力由 compactor 组件统一承载。本文基于当前仓库的官方文档与源码实现系统讲解删除功能的前置条件、compactor 配置项、三种deletion_mode语义、删除请求的创建/查询/取消 API 参数以及删除请求在后端的存储、分片与执行机制帮助你安全、正确地落地日志删除与合规需求。功能概述Loki 能删除什么Grafana Loki 的日志条目删除功能允许你从**指定流stream**中删除日志满足以下条件的日志条目会被删除落在指定的时间窗口内匹配一个可选的 LogQL 行过滤器line filter。删除请求通过 compactor 组件暴露的 REST 端点提交端点列表见 reference/loki-http-api 中的 compactor 部分由请求指定流与时间窗口日志条目的实际删除动作则在可配置的**取消期cancellation period**过后才会发生。需要特别注意的是索引存储类型的约束日志条目删除在TSDB 索引作为索引存储时受支持过时的 BoltDB Shipper 索引也支持该功能但 BoltDB Shipper 将在 Loki 4.0 中被移除因此新部署应使用 TSDB。日志条目删除依赖自定义日志保留custom logs retention工作流——即 compactor 的 retention 机制。compactor 会检查所有未处理且已超过取消期的删除请求据此判断某个 chunk 是否应该被删除。开启删除功能的前置条件日志删除不是开箱即用的需要同时满足三个条件启用 retention在 compactor 配置中设置retention_enabled: true命令行对应-compactor.retention-enabled。配置delete_request_store指定存储删除请求的对象存储桶启用 retention 后必须配置否则 compactor 启动校验会直接失败见 pkg/compactor/config.go 中Validate()对DeleteRequestStore 的报错。租户的deletion_mode非disabled默认值为filter-and-delete因此在未显式修改的情况下一旦启用 retention 并配置好delete_request_store删除功能对所有租户即默认生效。⚠️ 启用 retention 的安全警告启用 retention 必须非常谨慎。强烈建议同时在对象存储上开启版本控制versioning以便在 retention 配置误操作时能够恢复数据。如果你只想启用删除能力、并不想强制执行 retention请将retention_period设置为0s。从源码看compactor 的Validate()还做了一些自动化的配置协调pkg/compactor/config.go当retention_enabled为 true 且apply_retention_interval为 0 时它会将apply_retention_interval对齐为compaction_interval的值并额外增加最多 10 分钟不超过其一半的抖动jitter以避免 retention 与 compaction 在同一时刻运行。配置详解compactor 与 limits_configdeletion_mode三种模式deletion_mode是limits_config中的全局与按租户设置其类型定义在 pkg/validation/limits.golimits_config: # 全局默认可选值disabled | filter-only | filter-and-delete deletion_mode: filter-and-delete在全局配置文件中设置即为全局默认值也可以按租户在**运行时配置文件runtime configuration file**中覆盖参见 configure 文档的 runtime-configuration-file 部分。deletion_mode支持三种取值实现见 pkg/compactor/deletionmode/mode.go取值语义存储行为disabled不允许删除对删除 API 端点的请求返回403 Forbidden不删除filter-only查询 Loki 时过滤掉匹配删除请求的日志行不从存储中移除filter-and-delete查询时过滤且同时从存储中移除从存储删除默认值源码中Mode.DeleteEnabled()仅对FilterOnly与FilterAndDelete返回 truemode.go而删除 API 的请求处理会先调用validDeletionLimit检查租户模式是否允许删除pkg/compactor/deletion/util.go。注意ParseMode对未知值会返回ErrUnknownMode因此配置拼写错误会直接导致请求校验失败。端点注册与 retention 的强绑定删除 API 端点仅在compactor.retention_enabled为 true 时注册。当 retention 未启用时无论deletion_mode取什么值所有租户都无法访问删除端点此时请求处理器的 handler 为 nil会直接返回400 Retention is not enabled见 pkg/compactor/deletion/request_handler.go。当 retention 启用后再通过deletion_mode的按租户覆盖override来控制哪些租户可以使用删除 API。其他关键 compactor 配置项以下是当前仓库中与删除相关的完整配置项默认值与含义来自 pkg/compactor/config.gocompactor: # 启用按流/按租户的自定义 retention删除功能的前提 retention_enabled: true # 存储删除请求的对象存储桶启用 retention 后必填 delete_request_store: loki-delete-requests # 删除请求在桶中的路径前缀默认 index/ delete_request_store_key_prefix: index/ # 存储删除请求所用的数据库类型boltdb默认或 sqlite delete_request_store_db_type: boltdb # 迁移数据库类型时的备份库类型例如 boltdb backup_delete_request_store_db_type: # 允许在创建后多长时间内取消删除请求默认 24h delete_request_cancel_period: 24h # 带行过滤器的删除请求最大分片跨度默认 24h delete_max_interval: 24h # 每个压缩周期最多处理的删除请求数默认 70 delete_batch_size: 70 # retention 生效周期0 表示与 compaction 周期一致源码会自动加抖动 apply_retention_interval: 0s # 删除请求开始真正删除数据前的延迟默认 2h retention_delete_delay: 2h # 删除 chunk 的工作协程数默认 150 retention_delete_worker_count: 150对应的命令行 Flag前缀均为-compactor.Flag默认值-compactor.retention-enabledfalse-compactor.delete-request-store空-compactor.delete-request-store.key-prefixindex/-compactor.delete-request-store.db-typeboltdb-compactor.delete-request-store.backup-db-type空-compactor.delete-request-cancel-period24h-compactor.delete-max-interval24h-compactor.delete-batch-size70-compactor.retention-delete-delay2h-compactor.retention-delete-worker-count150源码中delete_request_cancel_period的 Flag 注释建议至少设为 24hconfig.goretention_delete_delay则是在取消期之后、chunk 真正被删除之前的额外缓冲。一个最小可用配置示例limits_config: retention_period: 744h # 如不想强制 retention可设为 0s deletion_mode: filter-and-delete compactor: working_directory: /var/loki/compactor retention_enabled: true delete_request_store: gcs://bucket_for_delete_requests # 按你的对象存储类型填写 delete_request_store_db_type: boltdb delete_request_cancel_period: 24h delete_max_interval: 24h删除请求的生命周期与 HTTP API 使用提交删除请求Add通过 compactor 的删除端点提交删除请求。核心参数在 request_handler.go 中解析query必填LogQL 流选择器表达式如{clusterprod}可带行过滤器如{clusterprod} | ERROR。源码中parseDeletionQuery会先syntax.ParseLogSelector再构建 Pipeline非法表达式如错误的 regex 或ip()模式会在提交时就返回 400而不是等到执行期失败pkg/compactor/deletion/util.go。start必填起始时间支持Unix 秒或RFC3339格式。end必填结束时间同样支持两种格式。校验规则包括不允许删除未来时间的数据deletes in the future are not allowed且 start 必须小于 endrequest_handler.go。max_interval可选单请求的分片跨度不能大于delete_max_interval也不能大于待删除时间窗口本身最小 1 秒合法单位为s、m、hrequest_handler.go。curl -X POST -H X-Scope-OrgID: tenant1 \ http://loki-compactor:3100/loki/api/v1/delete?query%7Bcluster%3D%22prod%22%7Dstart1704067200end1704153600成功时返回204 No Content响应头X-Delete-Request-ID携带删除请求 ID。请求只影响查询层时filter-only删除记录同样会持久化查询时由查询路径按需过滤。分片sharding机制删除请求如果带行过滤器会被拆分成多个较小的子请求每个子请求覆盖不超过delete_max_interval默认 24h的时间跨度。单个请求可以用max_interval参数请求更小的分片但不能大于delete_max_interval。不带行过滤器的删除请求不会被拆分request_handler.go 中仅当parsedExpr.HasFilter()时才计算分片间隔。源码中的buildRequests展示了分片的实现细节request_handler.go分片时子请求之间刻意保留少量时间重叠而不是精确衔接以避免因边界 1ms 的间隙漏删日志。查询删除请求Getcurl -H X-Scope-OrgID: tenant1 \ http://loki-compactor:3100/loki/api/v1/delete该接口按创建时间排序返回该租户的全部删除请求JSON 数组并隐藏内部的UserID与SequenceNum字段。它还支持两个可选参数for_querytime_filteringtrue仅返回与查询时过滤相关的删除请求startend可选的时间范围重叠过滤只返回与给定范围有交集的删除请求request_handler.go。被拆分出的同一请求的多个子请求在查询时会被mergeDeletes合并展示为一条状态根据已完成子请求的比例计算为Received、Processed或N% Completerequest_handler.go。取消删除请求Cancel删除请求在可配置的取消期内可以取消curl -X PUT -H X-Scope-OrgID: tenant1 \ http://loki-compactor:3100/loki/api/v1/delete?request_idREQUEST_ID取消期的长度由delete_request_cancel_period决定默认24h一旦请求进入处理中或已完成状态为Processed默认不允许取消返回 400对已开始处理或已超过创建后取消期的请求仍可传入forcetrue查询参数强制取消request_handler.gocurl -X PUT -H X-Scope-OrgID: tenant1 \ http://loki-compactor:3100/loki/api/v1/delete?request_idREQUEST_IDforcetrue缓存失效辅助端点compactor 还暴露了缓存代数cache generation number相关端点GET /loki/api/v1/cache_generation_number用于获取某租户的缓存代数POST更新端点用于在回放历史数据等场景下手动递增缓存代数使该租户的查询结果缓存失效request_handler.go。删除处理完成后缓存代数会自动更新从而保证查询不会命中已删除数据的缓存。删除请求的存储boltdb 与 sqlite以及迁移删除请求本身使用delete_request_store_db_type指定的数据库类型存储默认为boltdb也可改用sqlite。从一种数据库类型迁移到另一种时可以设置backup_delete_request_store_db_type: boltdb使删除请求同时写入备份数据库迁移期间不丢请求当前仓库中备份库仅支持 boltdb见 config.go。底层实现分别位于 pkg/compactor/deletion/delete_requests_db_boltdb.go 与 pkg/compactor/deletion/delete_requests_db_sqlite.go并配套完整的单元测试delete_requests_db_boltdb_test.go、delete_requests_db_sqlite_test.go可作为实现参考。注意delete_request_store与delete_request_store_db_type是两个不同维度的配置——前者是对象存储位置存放删除请求数据文件后者是本地数据库引擎。二者的组合决定了删除请求的持久化方式。删除的实际执行机制删除不是提交请求后立即发生的其执行链路如下compactor 周期性扫描compactor 在每个 retention 周期apply_retention_interval默认与 compaction 周期一致并带抖动检查未处理的删除请求。只处理已过取消期的请求只有创建时间超过delete_request_cancel_period默认 24h的请求才会进入实际删除阶段这是给用户留出取消窗口。批量执行每个周期最多处理delete_batch_size默认 70个删除请求。真正的数据删除对于filter-and-delete模式涉及删除的 chunk 需要按删除请求重建去除被删除的行再写回对象存储并更新索引删除动作还会受到retention_delete_delay默认 2h的进一步延迟缓冲。从源码看delete_requests_manager.go 中的DeleteRequestsManager负责加载待处理的删除请求loadDeleteRequestsToProcess并以chunksSelectedTotal、deletedLinesTotal、deleteRequestsProcessedTotal、deletionFailures等指标持续上报进度metrics.go。带行过滤器的删除请求重建 chunk 的过程由 deletion_manifest_builder.go 生成删除清单deletion manifest驱动。⚠️ 性能注意事项带行过滤器的日志删除是 compactor 最消耗资源的操作之一。因为带过滤器的删除需要把每个相关 chunk 读出来、剔除匹配行、再重写并写回对象存储属于 CPU 与 IO 密集任务。如果需要在多个租户/流上删除大批量带行过滤器的数据请参考 Horizontal scaling of Compactor将删除工作分布到多个 compactor 实例上执行。排查与运维建议对象存储务必开启版本控制防止误删后无法恢复先以filter-only模式观察删除查询的实际命中范围再切换到filter-and-delete落地物理删除提交带行过滤器的删除请求时合理利用max_interval参数控制单次分片规模避免单个请求跨度过大导致执行时间过长监控 compactor 的删除相关指标loki_compactor_deletion_*观察请求积压与执行失败情况必要时通过横向扩展 compactor 分散负载。总结Loki 的日志条目删除能力以 compactor 的 retention 工作流为底座通过retention_enableddelete_request_storedeletion_mode三个要素即可开启删除请求经 REST API 提交后先经历可取消的保护期再由 compactor 周期性地完成过滤、chunk 重建与物理删除。理解filter-only与filter-and-delete的差异、分片与取消机制、以及 boltdb/sqlite 两种请求存储的迁移方式是安全使用这一强操作能力的关键。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考