如何制定并实践Promtail日志采集的详细配置规范？

# Promtail 日志采集配置规范 > 标准化日志采集配置指南，适用于基于 Promtail + Loki 的日志收集架构。 --- ## 目录 - [架构概览](#架构概览) - [配置结构说明](#配置结构说明) - [标签规范](#标签规范) - [Pipeline Stages 详解](#pipeline-stages-详解) - [标准配置模板（通用版）](#标准配置模板通用版) - [现有配置分析与优化](#现有配置分析与优化) - [运维操作手册](#运维操作手册) - [常见问题排查](#常见问题排查) --- ## 架构概览 ``` Application Logs (file) └─> Promtail (tail + label + pipeline) └─> Loki Gateway (push API) └─> Loki (存储 + 索引) └─> Grafana (查询 + 告警) ``` **核心流程：** 1. 应用将日志写入本地文件（按约定目录结构） 2. Promtail 以 tail 方式持续读取日志文件 3. Pipeline stages 对日志行进行解析、打标签、多行合并 4. 带标签的日志推送至 Loki Gateway --- ## 配置结构说明 Promtail 配置分为四大块： ```yaml server: # HTTP/gRPC 监听端口 positions: # 读取位置记录（断点续传） clients: # Loki 推送目标 scrape_configs: # 日志采集任务定义 ``` ### server ```yaml server: http_listen_port: 3100 # Promtail 自身 metrics/health 端口 grpc_listen_port: 0 # 0 = 禁用 gRPC ``` ### positions ```yaml positions: filename: /var/lib/promtail/positions.yaml # 记录每个文件的读取偏移量 sync_period: 10s # 刷盘周期 ``` > **重要：** `positions` 保证 Promtail 重启后从上次位置继续读取，不丢失也不重复。生产环境必须配置。 ### clients ```yaml clients: - url: http://loki-gateway.example.com/loki/api/v1/push external_labels: env: prod # 全局标签，标识环境 region: ap-northeast-1 # 全局标签，标识区域 batchwait: 1s # 批量发送等待时间 batchsize: 1048576 # 批量大小（1MB） timeout: 10s # 推送超时 ``` ### scrape_configs 每个 `job_name` 定义一组采集任务，包含： - `static_configs`：目标文件路径和静态标签 - `pipeline_stages`：日志处理管道 --- ## 标签规范 ### 原则 | 原则 | 说明 | |------|------| | 低基数 | 标签值种类应有限（< 100），避免高基数导致 Loki 索引膨胀 | | 稳定性 | 标签值不应频繁变化（IP、时间戳等**不可**作为标签） | | 可查询 | 标签应服务于常见查询场景：按环境、应用、日志级别过滤 | ### 标准标签集 | 标签 | 来源 | 示例 | 说明 | |------|------|------|------| | `env` | `external_labels` | `prod`, `uat`, `sit` | 部署环境 | | `region` | `external_labels` | `ap-northeast-1` | 区域 | | `app` | pipeline 动态提取 | `trading-gateway` | 应用名称 | | `severity` | pipeline 动态提取 | `info`, `warn`, `error` | 日志级别 | | `job` | `job_name` 自动生成 | `java-app-logs` | 采集任务名 | ### 反模式 ```yaml # BAD - 高基数标签，会导致 Loki 性能严重下降 labels: pod_ip: 10.0.1.23 request_id: abc-123 user_id: 12345 timestamp: "2026-04-10T12:00:00Z" # GOOD - 低基数、稳定、可查询 labels: app: trading-gateway severity: error ``` --- ## Pipeline Stages 详解 Pipeline stages 按顺序处理每一行日志，常用 stage 如下： ### multiline — 多行合并 Java 堆栈跟踪等跨行日志必须合并为单条： ```yaml pipeline_stages: - multiline: firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}' # 新日志行的起始模式 max_wait_time: 3s # 等待下一行的最大时间 max_lines: 128 # 单条日志最大行数 ``` | 参数 | 推荐值 | 说明 | |------|--------|------| | `firstline` | 按日志框架调整 | 匹配新日志条目的首行 | | `max_wait_time` | `3s` | 太短会截断堆栈，太长会增加延迟 | | `max_lines` | `128` | 防止异常情况下无限合并 | ### regex — 正则提取 从文件名或日志内容中提取标签值： ```yaml # 从文件名提取 app 和 severity - regex: expression: '^/data/logs/(?P<app>[^/]+)/.+\.log$' source: filename - regex: expression: '.*(?P<severity>error|info|warn|debug|fatal)\.log$' source: filename ``` ### labels — 设置标签 将提取的值设为 Loki 标签： ```yaml - labels: app: # 使用 regex 阶段提取的 app 值 severity: # 使用 regex 阶段提取的 severity 值 ``` ### template — 值转换 对提取的值进行格式化： ```yaml - template: source: app template: 'myprefix-{{ .Value }}' # 添加前缀 ``` ### drop — 丢弃日志 过滤掉不需要的日志（如健康检查）： ```yaml - drop: expression: '.*healthcheck.*' drop_counter_reason: healthcheck ``` ### limit_stage — 速率限制 防止日志洪泛打爆 Loki： ```yaml - limit: rate: 100 # 每秒最大行数 burst: 200 # 突发容量 drop: true # 超限丢弃（false = 背压） ``` --- ## 标准配置模板（通用版） 以下为优化后的通用模板，采用**统一目录规范 + 动态标签提取**，新增应用无需修改 Promtail 配置。 ### 日志目录规范（前提） ``` /data/logs/{app-name}/{app-name}-{severity}.log 示例： /data/logs/trading-gateway/trading-gateway-info.log /data/logs/trading-gateway/trading-gateway-error.log /data/logs/trading-gateway/trading-gateway-warn.log /data/logs/order-service/order-service-info.log /data/logs/order-service/order-service-error.log ``` > 只要应用按此目录结构输出日志，Promtail 自动识别，**零配置接入**。 ### 完整配置 ```yaml # ============================================================================= # Promtail 标准配置模板 # 适用：Java / Go / Python 应用日志采集 # 要求：日志输出至 /data/logs/{app-name}/ 目录 # ============================================================================= server: http_listen_port: 3100 grpc_listen_port: 0 log_level: warn # promtail 自身日志级别 positions: filename: /var/lib/promtail/positions.yaml sync_period: 10s # ----------------------------------------------------------------------------- # Loki 推送目标 # ----------------------------------------------------------------------------- clients: - url: http://loki-gateway.example.com/loki/api/v1/push external_labels: env: prod # 按环境修改：prod / uat / sit / dev region: ap-northeast-1 # 按区域修改 batchwait: 1s batchsize: 1048576 # 1MB timeout: 10s # ----------------------------------------------------------------------------- # 采集任务 # ----------------------------------------------------------------------------- scrape_configs: # =========================================================================== # Job 1: 标准应用日志（通用，自动发现） # 目录结构: /data/logs/{app-name}/*{severity}.log # =========================================================================== - job_name: app-logs static_configs: - targets: [localhost] labels: __path__: /data/logs/*/*info.log - targets: [localhost] labels: __path__: /data/logs/*/*warn.log - targets: [localhost] labels: __path__: /data/logs/*/*error.log - targets: [localhost] labels: __path__: /data/logs/*/*debug.log - targets: [localhost] labels: __path__: /data/logs/*/*fatal.log pipeline_stages: # Step 1: 多行合并（Java 堆栈跟踪） - multiline: firstline: '^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}' max_wait_time: 3s max_lines: 128 # Step 2: 从文件路径提取 app 名称 - regex: expression: '^/data/logs/(?P<app>[^/]+)/.+\.log$' source: filename # Step 3: 从文件名提取日志级别 - regex: expression: '.*(?P<severity>error|info|warn|debug|fatal)\.log$' source: filename # Step 4: 设置标签 - labels: app: severity: # Step 5: 丢弃健康检查等噪音日志（按需启用） # - drop: # expression: '.*(healthcheck|readiness|liveness).*' # drop_counter_reason: health_probe # Step 6: 速率限制（按需启用） # - limit: # rate: 500 # burst: 1000 # drop: true # =========================================================================== # Job 2: 遗留应用日志（兼容旧目录结构） # 目录结构: /data/api/{app-name}-{severity}.log # =========================================================================== - job_name: legacy-app-logs static_configs: - targets: [localhost] labels: __path__: /data/api/*info.log - targets: [localhost] labels: __path__: /data/api/*warn.log - targets: [localhost] labels: __path__: /data/api/*error.log - targets: [localhost] labels: __path__: /data/api/*debug.log pipeline_stages: - multiline: firstline: '^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}' max_wait_time: 3s max_lines: 128 - regex: expression: '^/data/api/(?P<app>.+)-(?P<severity>error|info|warn|debug)\.log$' source: filename # 添加统一前缀（可选，与新目录区分） # - template: # source: app # template: 'legacy-{{ .Value }}' - labels: app: severity: # =========================================================================== # Job 3: 专用应用日志（特殊日志文件名不符合通用规则时使用） # =========================================================================== - job_name: special-app-logs static_configs: - targets: [localhost] labels: __path__: /data/api/**/logs/rapidtrade_server.log app: rapidtrade-server severity: all - targets: [localhost] labels: __path__: /data/api/**/logs/exchange.log app: rapidtrade-server severity: all pipeline_stages: - multiline: firstline: '^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}' max_wait_time: 3s max_lines: 128 ``` --- ## 现有配置分析与优化 ### 原始配置问题 | 问题 | 影响 | 优化方案 | |------|------|----------| | 缺少 `positions` 配置 | Promtail 重启后重头读取，日志重复推送 | 添加 `positions` 段 | | 多个 job 重复定义相同 pipeline | 维护成本高，修改需改多处 | 合并为通用 job + 动态标签提取 | | `max_wait_time` 不一致（1s / 4s） | 行为不可预测 | 统一为 `3s` | | 缺少 `max_lines` 限制 | 异常堆栈可能无限合并 | 添加 `max_lines: 128` | | firstline 正则不兼容 ISO 8601 | `2026-04-10T12:00:00` 格式无法匹配 | 改为 `^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}` | | 无速率限制 | 日志洪泛可能打爆 Loki | 按需添加 `limit` stage | | 无噪音过滤 | 健康检查日志浪费存储 | 添加 `drop` stage | | `rapidx-log` 与 `rapidx-log-new` 功能重叠 | 同一日志可能被采集两次 | 按目录结构拆分为两个不重叠的 job | ### 优化前后对比 ``` 优化前（6 个 job，大量重复）： ├── rapidtrade-server-log # 硬编码 app 标签 ├── rapidtrade-quote-log # 硬编码 app 标签 ├── rapidtrade-order-log # 硬编码 app 标签 ├── rapidx-log-new # /data/logs/ 动态提取（好） ├── rapidx-log # /data/api/ 动态提取（好） └── （缺 positions） 优化后（3 个 job，通用 + 兼容 + 特殊）： ├── app-logs # /data/logs/ 通用，动态提取 app + severity ├── legacy-app-logs # /data/api/ 兼容旧结构 ├── special-app-logs # 特殊命名文件，手动指定标签 └── positions ✓ ``` --- ## 运维操作手册 ### 部署 Promtail ```bash # 1. 安装（以 systemd 为例） sudo useradd --system --no-create-home promtail sudo mkdir -p /var/lib/promtail /etc/promtail # 2. 放置配置文件 sudo cp promtail-config.yaml /etc/promtail/config.yaml # 3. 创建 systemd service cat <<'EOF' | sudo tee /etc/systemd/system/promtail.service [Unit] Description=Promtail Log Collector After=network.target [Service] Type=simple User=promtail ExecStart=/usr/local/bin/promtail -config.file=/etc/promtail/config.yaml Restart=on-failure RestartSec=5s LimitNOFILE=65536 [Install] WantedBy=multi-user.target EOF # 4. 启动 sudo systemctl daemon-reload sudo systemctl enable --now promtail # 5. 验证 curl -s http://localhost:3100/ready # 就绪检查 curl -s http://localhost:3100/metrics # Prometheus 指标 ``` ### 新应用接入 **场景 A：符合目录规范（零配置）** ```bash # 应用只需将日志输出到指定目录，无需修改 Promtail mkdir -p /data/logs/my-new-app/ # 应用配置日志输出： # /data/logs/my-new-app/my-new-app-info.log # /data/logs/my-new-app/my-new-app-error.log # Promtail 自动发现并采集，app=my-new-app, severity=info/error ``` **场景 B：特殊日志路径** ```yaml # 在 special-app-logs job 的 static_configs 中追加： - targets: [localhost] labels: __path__: /opt/custom-app/output/*.log app: custom-app severity: all ``` ### 配置变更流程 ```bash # 1. 编辑配置 vim /etc/promtail/config.yaml # 2. 语法检查（dry-run） promtail -config.file=/etc/promtail/config.yaml -dry-run # 3. 重载配置（无需重启） curl -X POST http://localhost:3100/reload # 或 sudo systemctl reload promtail # 4. 验证采集状态 curl -s http://localhost:3100/targets | python3 -m json.tool ``` ### 关键监控指标 ```promql # Promtail 推送到 Loki 的速率 rate(promtail_sent_entries_total[5m]) # 推送失败率 rate(promtail_dropped_entries_total[5m]) # 文件读取延迟（tail 落后字节数） promtail_file_bytes_total - promtail_read_bytes_total # 目标文件数量 promtail_targets_active_total ``` --- ## 常见问题排查 ### 日志未被采集 ```bash # 1. 检查文件权限 ls -la /data/logs/my-app/ # promtail 用户需有读权限 # 2. 检查 target 状态 curl -s http://localhost:3100/targets | grep my-app # 3. 检查 glob 是否匹配 # __path__ 支持 * 和 **，但不支持 {} # * 匹配单层目录，** 匹配多层目录 # 4. 检查 positions 文件 cat /var/lib/promtail/positions.yaml | grep my-app ``` ### 日志重复 ```bash # 原因：多个 job 的 __path__ 匹配了同一个文件 # 排查：检查各 job 的 __path__ 是否存在重叠 # 修复：确保每个文件只被一个 job 匹配 # 验证当前 target 分配 curl -s http://localhost:3100/targets | python3 -c " import sys, json data = json.load(sys.stdin) paths = {} for target in data: path = target.get('labels', {}).get('__path__', '') job = target.get('labels', {}).get('job', '') paths.setdefault(path, []).append(job) for path, jobs in paths.items(): if len(jobs) > 1: print(f'DUPLICATE: {path} -> {jobs}') " ``` ### Java 堆栈被拆成多条 ```yaml # 原因：multiline firstline 正则不匹配或 max_wait_time 太短 # 排查： # 1. 确认日志首行格式 head -5 /data/logs/my-app/my-app-error.log # 2. 测试正则是否匹配 echo "2026-04-10 12:00:00.123 ERROR ..." | grep -P '^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}' # 3. 如使用 logback/log4j2，常见 firstline 模式： # ^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2} # 通用 # ^\[\d{4}-\d{2}-\d{2} # 带方括号 # ^\d{2}:\d{2}:\d{2}\.\d{3} # 仅时间 ``` ### Promtail 内存占用过高 ```bash # 原因：采集文件过多或日志量过大 # 排查： curl -s http://localhost:3100/metrics | grep promtail_targets_active # 优化： # 1. 收窄 __path__ glob 范围 # 2. 启用 limit stage 限速 # 3. 启用 drop stage 过滤噪音 # 4. 减少 batchsize ```