Promtail JSON 过滤采集方案 v1.3

零侵入 · 防爆炸 · 生产级

适用：K8s 1.20+ / 裸机 / 容器混合场景

目标：业务只输出单行 JSON，采集层（Promtail/Vector）负责解析、采样、标签和告警。

统一日志格式（业务唯一约束）

建议业务统一输出单行 JSON（最小必需字段）：

{
  "ts":"2026-01-23T14:23:45.123Z",
  "level":"INFO|WARN|ERROR",
  "logger":"c.x.Foo",
  "msg":"...",
  "traceId":"a1b2c3",
  "uri":"/api/order",
  "duration":120,
  "userId":123456,
  "event":"order_create|login|APP_START|security|slow_sql",
  "error":"NullPointerException: xxx"
}

无异常 → error=""
慢调用 → duration>500
审计/安全/生命周期 → event=xxx

logback-spring.xml 模板（建议使用 AsyncAppender）

<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeContext>true</includeContext>
        <provider class="net.logstash.logback.composite.loggingevent.LoggingEventPatternJsonProvider">
            <pattern>{"ts":"%d{yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}","level":"%level","logger":"%logger","msg":"%msg","traceId":"%X{traceId:-}","uri":"%X{uri:-}","duration":"%X{duration:-0}","userId":"%X{userId:-}","event":"%X{event:-}","error":"%X{error:-}"}</pattern>
        </provider>
    </encoder>
</appender>
<appender name="ASYNC_JSON" class="ch.qos.logback.classic.AsyncAppender">
  <appender-ref ref="JSON" />
</appender>
<root level="INFO"><appender-ref ref="ASYNC_JSON"/></root>

Promtail 配置总览（核心思路）

文件：/etc/promtail/config.yml

核心思路：三段减压 → 低基数标签 → 哈希采样 → 异常/慢调用/审计多分支

要点：

0 级：直接丢弃 DEBUG/TRACE（快速判断，避免解析开销）
1 级：关键词保留（仅保留 ERROR、审计事件、慢调用等）
2 级：WARN 采样（例如 10%）
在做深度 JSON 解析前尽量完成 drop/采样，减少解析次数
只把低基数字段作为 labels（level, event, namespace, exception_type）

示意 pipeline（思路性，不逐字复制配置）：

# 伪配置：快速按 level drop -> 关键词保留 -> WARN 采样 -> json解析 -> timestamp -> labels

资源占用参考（4C8G 节点）

阶段	CPU	内存	说明
原始全量 JSON 解析	150-200%	400 MB	无过滤
加三段减压阀后	30-40%	120 MB	同集群实测
若换 Vector 解析	10-15%	100 MB	Promtail 仅转发

存储与爆炸兜底
标签基数门禁：上线前脚本扫描 24h 日志，任一标签唯一值 >5000 即阻断发布。
Loki 整流示例：

limits_config:
  per_stream_rate_limit: 3MB
  per_stream_rate_limit_burst: 5MB
  ingestion_rate_mb: 10
  ingestion_burst_size_mb: 20

超限直接丢弃并暴露 rate_limit_discarded_bytes 指标。

Retention：audit 流 365d，其余 7d，存到 S3/OSS。

基数扫描示例（CI/部署前）：

logcli query '{env="prod"}' --since=24h | jq -r '.[].event' | sort | uniq -c | awk '$1>5000{print $2, $1}'

LogQL 告警模板（Grafana 可直接导入）

# 1. 异常突增（对比 1h 前）
sum by (exception_type) (
  rate({level="ERROR"}[5m])
) > 1.5 * sum by (exception_type) (
  rate({level="ERROR"}[1h] offset 1h)
)

# 2. 慢调用 P99 超 1s
quantile_over_time(0.99,
  {slow="true"} | unwrap duration [5m]
) by (uri) > 1000

# 3. 审计事件下降
sum(rate({log_type="audit"}[5m])) by (event) < 0.5 * sum(rate({log_type="audit"}[1h] offset 1h)) by (event)

补充告警（解析/丢弃监控）：

sum(rate(promtail_parsing_errors_total[5m])) > 0
rate(loki_ingester_discarded_bytes_total[5m]) > 0
rate(promtail_dropped_bytes_total[5m]) > 0

运维 checklist

每日

kubectl top pod -l app=promtail 单核 CPU <500m
基数预警（部署前/CI 运行）

每周

检查 rate(promtail_dropped_bytes_total[5m]) > 0

每月

回顾并调整 per_stream_rate_limit 与采样策略

新增：在 Helm/Chart CI 中加入基数检测脚本，阻断高基数 label 的发布并在 PR 中给出样例。

升级顺序与迁移建议

升级顺序（推荐）： Vector（可选）→ Loki → Promtail → Grafana

迁移步骤（简要）

在 Staging 双写到旧流/新流 72h 对比告警与查询；
Canary（10% 节点）逐步扩大并监控 parsing_errors、dropped_bytes；
全量切换并观察 24-72h，若异常立即回滚并恢复双写。

回滚：使用 Git/Helm release 回退到上一个成功版本。

开发者 & 运维附录

建议把以下示例文件纳入 repo：

logback-spring.xml 模板（AsyncAppender）
LoggingFilter.java（Servlet Filter 示例）
ci/check_cardinality.sh（CI 门禁脚本）

Log-operation-full.md 4.8 KB 履歴 Raw

Promtail JSON 过滤采集方案 v1.3

Log-operation-full.md 4.8 KB

履歴 Raw