从 Promtail 迁移到 Grafana Alloy

内置的 Alloy convert 命令可以将您的 Promtail 配置迁移到 Alloy 配置。

本主题介绍如何：

将 Promtail 配置转换为 Alloy 配置。
使用 Alloy 原生运行 Promtail 配置。

本主题中使用的组件

开始之前

您必须拥有 Promtail 配置。
您必须熟悉 Alloy 中的组件概念。

转换 Promtail 配置

要完全从 Promtail 迁移到 Alloy，您必须将 Promtail 配置转换为 Alloy 配置。此转换使您能够充分利用 Alloy 中提供的许多额外功能。

在此任务中，您使用 convert CLI 命令从 Promtail 配置输出 Alloy 配置。

打开终端窗口并运行以下命令。
shell
```
alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
替换以下内容
- <INPUT_CONFIG_PATH>: Promtail 配置的完整路径。
- <OUTPUT_CONFIG_PATH>: 输出 Alloy 配置的完整路径。
使用 <OUTPUT_CONFIG_PATH> 的新配置运行 Alloy

调试

如果 convert 命令无法转换 Promtail 配置，则会将诊断信息发送到 stderr。您可以通过包含 --bypass-errors 标志来绕过任何非关键问题，并尽力转换输出 Alloy 配置。
注意
如果您绕过错误，转换后的配置行为可能与原始 Promtail 配置不匹配。在生产环境中使用转换后的配置之前，请确保对其进行全面测试。
shell
```
alloy convert --source-format=promtail --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
替换以下内容
- <INPUT_CONFIG_PATH>: Promtail 配置的完整路径。
- <OUTPUT_CONFIG_PATH>: 输出 Alloy 配置的完整路径。

您还可以通过包含 --report 标志来输出诊断报告。

alloy convert --source-format=promtail --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

替换以下内容

<INPUT_CONFIG_PATH>: Promtail 配置的完整路径。
<OUTPUT_CONFIG_PATH>: 输出 Alloy 配置的完整路径。
<OUTPUT_REPORT_PATH>: 报告的输出路径。

如果您使用下面的示例 Promtail 配置，诊断报告会提供以下信息：

(Warning) If you have a tracing set up for Promtail, it cannot be migrated to Alloy automatically. Refer to the documentation on how to configure tracing in Alloy.
(Warning) The metrics from Alloy are different from the metrics emitted by Promtail. If you rely on Promtail's metrics, you must change your configuration, for example, your alerts and dashboards.

运行 Promtail 配置

如果您尚未准备好完全切换到 Alloy 配置，您可以使用 Promtail 配置运行 Alloy。--config.format=promtail 标志会告诉 Alloy 将您的 Promtail 配置转换为 Alloy 并直接加载，而无需保存新配置。这使您无需修改 Promtail 配置基础设施即可尝试 Alloy。

在此任务中，您使用 run CLI 命令运行 Alloy 并使用 Promtail 配置。

运行 Alloy 并包含命令行标志 --config.format=promtail。您的配置文件必须是有效的 Promtail 配置文件，而不是 Alloy 配置文件。

调试

您可以按照 convert CLI 命令的调试说明来生成诊断报告。
有关运行 Alloy 的更多信息，请参阅 Alloy 调试。
如果您的 Promtail 配置无法直接转换为 Alloy 并加载，则会将诊断信息发送到 stderr。您可以通过除了 --config.format=promtail 外，还包含 --config.bypass-conversion-errors 标志来绕过任何非关键问题并启动 Alloy。
注意
如果您绕过错误，转换后的配置行为可能与原始 Promtail 配置不匹配。请勿在生产环境中使用此标志。

示例

此示例演示了将 Promtail 配置文件转换为 Alloy 配置文件。

以下 Promtail 配置文件为转换提供输入。

clients:
  - url: https:///loki/api/v1/push
scrape_configs:
  - job_name: example
    static_configs:
      - targets:
          - localhost
        labels:
          __path__: /var/log/*.log

convert 命令将 YAML 文件作为输入并输出 Alloy 配置文件。

alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

替换以下内容

<INPUT_CONFIG_PATH>: Promtail 配置的完整路径。
<OUTPUT_CONFIG_PATH>: 输出 Alloy 配置的完整路径。

新的 Alloy 配置文件如下所示：

local.file_match "example" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/*.log",
  }]
}

loki.source.file "example" {
  targets    = local.file_match.example.targets
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "https:///loki/api/v1/push"
  }
  external_labels = {}
}

限制

配置转换是尽力而为的。对于无法执行转换的情况，Alloy 会发出警告或错误。

转换配置后，请查看创建的 Alloy 配置文件，并在生产环境中使用之前验证其正确性。

以下列表特定于 convert 命令，而非 Alloy：

检查您是否在使用 Promtail 时使用了配置文件中不存在的额外命令行参数。例如，-max-line-size。
检查您是否设置了任何环境变量，无论是在配置文件本身中展开的，还是 Promtail 直接使用的，例如 JAEGER_AGENT_HOST。
在 Alloy 中，positions 文件保存位置不同。有关详细信息，请参阅 loki.source.file 文档。检查您是否有任何设置，例如 Kubernetes 持久卷，需要更新才能使用新的 positions 路径。
Alloy 暴露的元监控指标通常与 Promtail 元监控指标匹配，但名称不同。请确保您使用新的指标名称，例如在您的告警和仪表盘查询中。
Alloy 生成的日志与 Promtail 生成的日志不同。
Alloy 暴露了 Alloy UI，它与 Promtail Web UI 不同。