Grafana Alloy 怎样把 OpenTelemetry Collector 配置迁移为 River

如果团队已经在用 OpenTelemetry Collector，迁移到 Grafana Alloy 时最容易混淆的是“能转换”和“能直接运行”其实是两件事。实际做法是：先保留原 YAML，使用 alloy convert --source-format=otelcol 输出 River 配置；若只是试用 Alloy，再用 --config.format=otelcol 直接加载旧格式。两条路径都应保留诊断信息和回退材料。

官方地址：https://grafana.com/docs/grafana-cloud/observe-and-act/send-data/alloy/set-up/migrate/from-otelcol/

迁移的最小闭环是“原配置可回退、转换结果可解释、组件连接能对应、切换范围可收回”，不要把生成了一个 River 文件当作生产迁移已经完成。

转换、兼容运行和生产切换不是同一个动作

Grafana Alloy 官方迁移文档给出了两种入口。convert 把 OpenTelemetry Collector 配置转换成 Alloy 配置，适合建立长期维护的 River 文件；--config.format=otelcol 则让 Alloy 读取旧格式并在加载时转换，适合先验证运行边界。前者改变配置资产，后者保留输入格式，回退成本不同。

因此第一步不是删除旧文件，而是给输入配置做一个可追溯副本，并把转换输出放在独立目录。若输出出现诊断信息，先记录问题属于组件缺失、字段不兼容还是语义需要人工改写，再决定是否继续。

先看组件怎样映射到 River

Collector 配置通常由 receivers、processors、exporters 和 service.pipelines 组成。迁移时不要只盯着 YAML 的缩进变化：真正要核对的是每个 receiver 是否仍接入目标信号、processor 是否在相同的管线位置、exporter 是否连到正确的 output，以及 metrics、logs、traces 三类 pipeline 是否都被覆盖。

下面是一个用于说明映射关系的最小 Collector 配置片段，地址和名称是教学占位，不代表已运行的生产配置：

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  memory_limiter:
    # 迁移时保留处理器的限制语义，具体阈值按环境重新评估
    limit_percentage: 90

exporters:
  otlp:
    # 示例端点仅用于说明导出边界，不能直接复制到生产
    endpoint: collector-backend:4317

service:
  pipelines:
    traces:
      # 这条链路展示接收、处理、导出的静态对应关系
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp]

转换后的 River 配置应能找到对应的 otelcol.receiver.otlp、otelcol.processor.memory_limiter 和 otelcol.exporter.otlp 组件，并通过 output 连接起来。节点名称可能变化，但数据语义不能靠“看起来差不多”判断。

用诊断报告区分可转换和需人工处理

正式转换时可以让命令同时输出报告：

# 将旧格式输入转换为 River，并把诊断写入独立文件
alloy convert \
  --source-format=otelcol \
  --report=alloy-convert-report.txt \
  --output=alloy-config.alloy \
  collector-config.yaml

# 查看诊断摘要；这里只读报告，不把警告当成成功证明
sed -n '1,120p' alloy-convert-report.txt

官方说明转换是 best-effort。遇到不能转换的部分，诊断会写到 stderr；--bypass-errors 可以输出尽力转换结果，但这不等于行为与原 Collector 完全一致。生产切换前，应把每条警告归类为可接受差异、需要手改的组件或必须停止的阻断问题。

如果团队还没准备好维护 River，也可以先直接加载旧格式：

# 试用阶段继续使用 Collector YAML，降低首次切换的配置改动面
alloy run \
  --config.format=otelcol \
  collector-config.yaml

这条路径的价值是缩小试验范围，而不是绕过迁移分析。旧配置仍须符合 Collector 语义，转换失败时同样应读取诊断；不要把 --bypass-errors 作为默认生产参数。

把切换和回退条件写成一张表

推荐先选一个低风险实例，保留旧配置和旧进程的回退路径，再扩大到同类节点。出现信号缺失、处理器语义变化或导出端拒绝时，应停止扩大范围，先根据报告定位差异。说明图和示例代码只解释结构，不代表已经连接实际环境或完成验收。

可以直接把 Collector YAML 改名为 .alloy 吗？

不可以。文件扩展名不会把 YAML 转成 River；要么使用 convert 生成 Alloy 配置，要么显式使用 --config.format=otelcol 让 Alloy按旧格式加载。

转换报告有 warning 就必须放弃吗？

不一定。先判断 warning 是否涉及数据语义、组件能力或仅是可解释的兼容提示；但不能直接忽略，生产前要保留处理结论和回退方案。

什么时候可以删掉旧 Collector 配置？

当 River 配置已被版本管理、关键 pipeline 有负责人核对、试点可回退窗口结束，并且旧格式不再承担应急恢复职责时再清理。迁移当天不要删除最后一份可用副本。

参考资料：Grafana Alloy 官方迁移文档、Grafana Alloy 迁移总览、OpenTelemetry Collector 官方配置说明。实际部署时应按所使用的 Alloy 版本和组件分发版重新阅读对应文档。