文档 Grafana Loki 发送数据 Promtail 故障排除

Promtail 故障排除

本文档描述了 Promtail 在边缘情况下的已知故障模式和所采用的权衡。

干运行

Promtail 可以配置为打印日志流条目而不是将其发送到 Loki。这可以与管道数据结合使用，以调试或排除 Promtail 日志解析的故障。

在干运行模式下，Promtail 仍然支持从位置文件中读取，但不会对目标文件进行更新，这确保了您可以轻松重试同一组行。

要以干运行模式启动 Promtail，请使用 `--dry-run` 标志，示例如下所示：

bash 复制

cat my.log | promtail --stdin --dry-run --client.url http://127.0.0.1:3100/loki/api/v1/push

检查配置文件

Promtail 可以验证您的 `config` 文件并进行语法检查，以确定配置是否有效。这可用于检查配置文件中的错误和不一致，并有助于防止部署无效配置。

在检查语法模式下，promtail 只会验证配置文件然后退出。

bash 复制

promtail -config.file=myConfigFile.yaml -check-syntax

检查管道阶段

Promtail 可以输出执行每个管道阶段时对日志条目进行的所有更改。每个日志条目包含四个字段

• 行
• timestamp
• labels
• 提取的字段

使用 `--inspect` 命令行选项启用检查输出。`--inspect` 选项可以与 `--stdin` 和 `--dry-run` 结合使用。

bash 复制

cat my.log | promtail --stdin --dry-run --inspect --client.url http://127.0.0.1:3100/loki/api/v1/push

输出使用颜色突出显示更改。新增内容为绿色，修改内容为黄色，删除内容为红色。

如果在某个阶段没有应用任何更改，这通常表示配置错误或出现非预期行为。

在生产环境中不应使用 `--inspect` 标志，因为计算管道阶段之间的更改会对 Promtail 的性能产生负面影响。

将数据管道到 Promtail

Promtail 支持管道数据以将日志发送到 Loki（通过 `--stdin` 标志）。这是一种非常有用的故障排除配置方法。一旦安装了 Promtail，您可以使用以下命令将日志发送到本地 Loki 实例

bash 复制

cat my.log | promtail --stdin  --client.url http://127.0.0.1:3100/loki/api/v1/push

您还可以使用命令行添加其他标签

bash 复制

cat my.log | promtail --stdin  --client.url http://127.0.0.1:3100/loki/api/v1/push --client.external-labels=k1=v1,k2=v2

这将添加标签 `k1` 和 `k2`，分别对应值 `v1` 和 `v2`。

在管道模式下，Promtail 也支持使用 `--config.file` 进行文件配置，但请注意，位置配置不被使用，并且仅使用**第一个 scrape 配置**。

static_configs: 可用于提供静态标签，尽管 targets 属性会被忽略。

如果您未提供任何scrape_config:，则会使用默认配置，该配置将自动添加以下默认标签：{job="stdin",hostname="<detected_hostname>"}。

例如，您可以使用下面的配置解析并为所有管道日志添加 `level` 标签

yaml 复制

clients:
  - url: https://:3100/loki/api/v1/push

scrape_configs:
- job_name: system
  pipeline_stages:
  - regex:
      expression: '(level|lvl|severity)=(?P<level>\\w+)'
  - labels:
      level:
  static_configs:
  - labels:
      job: my-stdin-logs

复制

cat my.log | promtail --config.file promtail.yaml

Promtail 未运行时被追踪文件被截断

假设以下事件顺序

1. Promtail 正在追踪 `/app.log`
2. Promtail 对于 `/app.log` 的当前位置是 `100` (字节偏移量)
3. Promtail 已停止
4. `/app.log` 被截断并追加了新的日志
5. Promtail 已重启

当 Promtail 重启时，它会从位置文件中读取之前的位置 (`100`)。此时可能会出现两种情况：

• `/app.log` 文件大小小于截断前的位置
• `/app.log` 文件大小大于或等于截断前的位置

如果 `/app.log` 文件大小小于之前的位置，则该文件被检测到已截断，日志将从位置 `0` 开始追踪。否则，如果 `/app.log` 文件大小大于或等于之前的位置，Promtail 无法检测到它在未运行时被截断，并将从位置 `100` 继续追踪文件。

一般来说，Promtail 在位置文件中仅使用文件的路径作为键。每当 Promtail 启动时，对于位置文件中引用的每个文件路径，如果文件大小小于位置文件中存储的偏移量，Promtail 将从头开始读取文件，否则将从偏移量继续，无论 Promtail 未运行时文件被截断或轮换了多少次。

Loki 不可用

对于每个被追踪的文件，Promtail 读取一行，通过配置的 pipeline_stages 处理，并将日志条目推送到 Loki。日志条目在推送到 Loki 之前会批量处理，基于最大批量持续时间 client.batch-wait 和大小 client.batch-size-bytes，以先达到的为准。

如果在发送日志条目批次时出现任何错误，Promtail 会采用“重试然后丢弃”的策略：

• Promtail 最多重试向 ingester 发送日志条目 max_retries 次。
• 如果所有重试都失败，Promtail 将丢弃该批日志条目（这些日志将丢失），然后继续处理下一个批次。

您可以通过 Promtail 配置文件中的 backoff_config 配置 max_retries 以及两次重试之间的延迟。

yaml 复制

clients:
  - url: INGESTER-URL
    backoff_config:
      min_period: 100ms
      max_period: 10s
      max_retries: 10

下表显示了使用 min_period: 100ms 和 max_period: 10s 的退避算法应用的总延迟示例：

Promtail 崩溃 / Panic / 意外终止后推送的日志条目

当 Promtail 正常关闭时，它会将最后读取的偏移量保存在位置文件中，以便在后续重启时能够继续追踪日志，而不会出现重复或丢失。

在发生崩溃或意外终止的情况下，Promtail 无法将最后读取的偏移量保存在位置文件中。重启后，Promtail 将读取上一次同步期间保存的位置文件，并从那里继续追踪文件。这意味着如果在上一次同步周期和崩溃之间读取并推送到 ingester 的新日志条目，在 Promtail 重启时这些日志条目将再次发送到 ingester。

如果 Loki 未配置为接受乱序写入，Loki 将拒绝接收到的所有它认为乱序的日志行。如果 Promtail 恰好崩溃，它可能会重新发送崩溃之前已发送的日志行。Promtail 的默认行为是在从被追踪文件中读取条目时为日志分配时间戳。这将导致重复的日志行发送到 Loki；为了避免这个问题，如果您的被追踪文件在日志行中嵌入了时间戳，则应在管道中添加一个 timestamp 阶段。