菜单
开源

run 命令

run 命令在前台运行 Alloy,直到接收到中断信号。

用法

shell
alloy run [<FLAG> ...] <PATH_NAME>

替换以下内容

  • <FLAG>: 一个或多个定义命令输入和输出的标志。
  • <PATH_NAME>: 必需。Alloy 配置文件/目录路径。

如果未提供 <PATH_NAME> 参数,或者在初始加载期间无法加载配置路径或配置路径包含错误,则 run 命令会立即退出并显示错误消息。

如果您为 <PATH_NAME> 参数指定一个目录路径,Alloy 会查找 *.alloy 文件(忽略嵌套目录)并将它们作为单个配置源加载。但是,组件名称在所有 Alloy 配置文件中必须是**唯一的**,并且配置块不得重复。

如果后续重新加载配置文件失败,Alloy 会继续运行,并可能根据故障性质将组件标记为不健康。发生这种情况时,Alloy 将继续在最后一次有效的状态下运行。

run 启动一个 HTTP 服务器,用于暴露自身及其组件的指标。该 HTTP 服务器还在 / 路径上提供一个 UI,用于调试正在运行的组件。

支持以下标志

  • --server.http.enable-pprof: 启用 /debug/pprof 性能分析端点。(默认 true)。
  • --server.http.memory-addr: 监听内存中 HTTP 流量的地址。(默认 alloy.internal:12345)。
  • --server.http.listen-addr: 监听 HTTP 流量的地址。(默认 127.0.0.1:12345)。
  • --server.http.ui-path-prefix: UI 暴露的基本路径。(默认 /)。
  • --storage.path: 组件存储数据的基本目录。(默认 data-alloy/)。
  • --disable-reporting: 禁用数据收集。(默认 false)。
  • --disable-support-bundle: 禁用支持包端点。(默认 false)。
  • --cluster.enabled: 在集群模式下启动 Alloy。(默认 false)。
  • --cluster.node-name: 此节点使用的名称(默认为环境主机名)。
  • --cluster.join-addresses: 加入集群的地址列表,以逗号分隔。(默认 "")。与 --cluster.discover-peers 互斥。
  • --cluster.discover-peers: 用于发现对等节点的键值对列表。(默认 "")。与 --cluster.join-addresses 互斥。
  • --cluster.rejoin-interval: 重新加入对等节点列表的频率。(默认 "60s")。
  • --cluster.advertise-address: 向其他集群节点通告的地址。(默认 "")。
  • --cluster.advertise-interfaces: 用于推断通告地址的接口列表。设置为 all 可使用系统上所有可用的网络接口。(默认 "eth0,en0")。
  • --cluster.max-join-peers: 从发现的对等节点集中加入的最大数量。(默认 5)。
  • --cluster.name: 用于阻止没有此标识符的节点加入集群的名称。(默认 "")。
  • --cluster.enable-tls: 指定对等节点之间是否应使用 TLS 进行通信。(默认 false)。
  • --cluster.tls-ca-path: 用于对等节点 TLS 通信的 CA 证书文件路径。
  • --cluster.tls-cert-path: 用于对等节点 TLS 通信的证书文件路径。
  • --cluster.tls-key-path: 用于对等节点 TLS 通信的密钥文件路径。
  • --cluster.tls-server-name: 用于对等节点 TLS 通信的服务器名称。
  • --cluster.wait-for-size: 等待集群达到指定数量的实例,然后允许使用集群功能的组件开始处理。零表示禁用。(默认 0)。
  • --cluster.wait-timeout: 等待最小集群大小的最大持续时间,超过后将使用可用节点继续。零表示无限期等待,无超时。(默认 0)。
  • --config.format: 源文件的格式。支持的格式:alloy, otelcol, prometheus, promtail, static。(默认 "alloy")。
  • --config.bypass-conversion-errors: 在转换时启用绕过错误。(默认 false)。
  • --config.extra-args: 转换器使用的原始格式中的额外参数。
  • --stability.level: 允许运行的功能的最低稳定性级别。支持的值:experimental, public-preview, generally-available。(默认 "generally-available")。
  • --feature.community-components.enabled: 启用社区组件。(默认 false)。
  • --feature.prometheus.metric-validation-scheme: 要使用的 Prometheus 指标验证方案。支持的值:legacy, utf-8。注意:这是一个实验性标志,未来版本可能会移除。(默认 "legacy")。
  • --windows.priority: 在 Windows 上运行时为 Alloy 进程设置的优先级。仅在 Windows 上可用。支持的值:above_normal, below_normal, normal, high, idle, 或 realtime。(默认 "normal")。

注意

--windows.priority 标志处于公开预览阶段,不受 Grafana Alloy 向后兼容性保证的覆盖。

更新配置文件

配置文件可以通过以下方式从磁盘重新加载:

  • /-/reload 端点发送 HTTP POST 请求。
  • 向 Alloy 进程发送 SIGHUP 信号。

发生这种情况时,组件控制器会将正在运行的组件集与配置文件中指定的最新组件集同步。重新加载后配置文件中不再定义的组件将被关闭,而自上次重新加载以来已添加到配置文件中的组件将被创建。

由组件控制器管理的所有组件在重新加载后都会被重新评估。

允许的稳定性级别

默认情况下,Alloy 只允许您使用标记为 正式可用 的功能。

要使用实验性公开预览功能,请将 --stability.level 标志设置为您想使用的级别

  • --stability.level=experimental: 使用标记为 实验性 及以上的功能。
  • --stability.level=public-preview: 使用标记为 公开预览 及以上的功能。
  • --stability.level=generally-available: 使用标记为 正式可用 的功能。

注意

--stability.level 设置为 experimentalpublic-preview 可能会启用其他标记为正式可用的项目的实验性或公开预览行为,例如:

  • 组件控制器
  • 主配置或导入模块中的组件
  • 主配置中的配置块

请参阅Grafana Labs 发布生命周期了解每个稳定性级别的定义。

集群

--cluster.enabled 命令行参数以集群模式启动 Alloy。其余的 --cluster.* 命令行标志可用于配置节点如何相互发现和连接。

每个集群成员的名称在集群内必须是唯一的。尝试使用冲突名称加入的节点将被拒绝,并回退到自举一个自己的新集群。

对等节点通过内置 HTTP 服务器使用 HTTP/2 进行通信。每个节点必须配置为接受 --server.http.listen-addr 和在 --cluster.advertise-address 中定义或推断的地址上的连接。

如果未明确设置 --cluster.advertise-address 标志,Alloy 会尝试从 --cluster.advertise-interfaces 推断一个合适的地址。如果未明确设置 --cluster.advertise-interfaces,Alloy 会从 eth0en0 本地网络接口推断一个地址。如果无法确定通告地址,Alloy 将无法启动。由于 Windows 不使用 eth0en0 接口名称,Windows 用户必须为 --cluster.advertise-interfaces 显式传递至少一个有效的网络接口,或为 --cluster.advertise-address 传递一个值。

--cluster.join-addresses 中提供的逗号分隔地址列表可以是 IP 地址或要查找的 DNS 名称(支持 SRV 和 A/AAAA 记录)。在这两种情况下,端口号都可以通过 :<port> 后缀指定。如果未提供端口,则使用 HTTP 监听器使用的默认端口。如果您未显式提供端口号,则必须确保所有实例都使用相同的端口作为 HTTP 监听器。

可以设置 --cluster.enable-tls 标志以启用对等通信的 TLS。需要额外的参数来配置 TLS 客户端,包括 CA 证书、TLS 证书、密钥和服务器名称。

--cluster.discover-peers 命令行标志需要一个元组列表,格式为 provider=XXX key=val key=val ...。集群使用 go-discover 包根据所选提供程序及其支持的过滤键值发现对等节点并获取其 IP 地址。集群支持 go-discover 中默认提供程序集,并额外注册了 k8s 提供程序。

如果元组对中的键或值包含空格、反斜杠或双引号,则必须使用双引号括起来。在此引用字符串中,反斜杠可用于转义双引号或反斜杠本身。

--cluster.rejoin-interval 标志定义了每个节点应根据 --cluster.join-addresses--cluster.discover-peers 标志的内容重新发现对等节点并尝试重新加入它们的频率。如果初始引导失败,此操作对于解决脑裂问题非常有用,并且使得在动态环境中管理集群更容易。要禁用此行为,请将 --cluster.rejoin-interval 标志设置为 "0s"

如果将 --cluster.rejoin-interval 设置为 0s,则使用 --cluster.join-addresses--cluster.discover-peers 标志发现对等节点仅在启动时发生。之后,集群节点依赖于相互交换 gossip 消息以达成集群状态的一致。

用于自举新集群的第一个节点(也称为“种子节点”)可以省略指定要加入的对等节点的标志,或者尝试连接到自身。

要加入或重新加入集群,Alloy 会尝试连接由 --cluster.max-join-peers 标志限制的随机数量的对等节点。此标志对于大型集群非常有用,因为连接到大量对等节点可能是一项昂贵的操作。要禁用此行为,请将 --cluster.max-join-peers 标志设置为 0。如果 --cluster.max-join-peers 的值高于发现的对等节点数量,Alloy 将连接所有这些节点。

--cluster.wait-for-size 标志指定了使用集群功能的组件开始处理流量所需的最小集群大小。当设置为大于零的值时,节点将加入集群,但使用集群功能的组件直到有足够的节点可用才会承担任何工作。这确保了足够的集群容量 - 请参阅估算资源使用量获取指导。默认值为 0,表示禁用此功能。

--cluster.wait-timeout 标志设置了一个节点等待集群达到 --cluster.wait-for-size 指定大小的最长时间。如果超时过期,节点将使用可用节点继续。将其设置为 0(默认值)表示无限期等待。对于生产环境,考虑设置一个几分钟的超时作为备用。

--cluster.name 标志可用于防止集群意外合并。提供 --cluster.name 时,节点仅加入共享相同集群名称值的对等节点。默认情况下,集群名称为空,未设置此标志的任何节点都可以加入。尝试使用错误的 --cluster.name 加入集群会导致“failed to join memberlist”错误。

集群状态

集群模式的 Alloy 处于以下三种状态之一

  • 观察者(Viewer): Alloy 对集群具有只读视图,不参与工作负载分发。
  • 参与者(Participant): Alloy 参与对启用集群功能的组件进行工作负载分发。
  • 终止中(Terminating): Alloy 正在关闭,不再为自身分配新工作。

每个 Alloy 最初以观察者状态加入集群,然后在进程启动完成后转变为参与者状态。每个 Alloy 在关闭时转变为终止中状态。

集群模式 Alloy 的当前状态显示在UI的集群页面上。

配置转换

公开预览: 这是一个公开预览组件。公开预览组件可能会发生重大变更,并可能被涵盖相同用例的等效功能取代。必须将 stability.level 标志设置为 public-preview 或更低才能使用该组件。

当您使用 --config.format 命令行参数指定 alloy 以外的值时,Alloy 会将源格式的配置文件转换为 Alloy 格式,并立即使用新配置开始运行。此转换使用alloy convert文档中描述的转换器 API。

如果您包含 --config.bypass-conversion-errors 命令行参数,Alloy 会忽略转换器中的错误。请谨慎使用此参数,因为生成的转换可能与原始配置不等效。

包含 --config.extra-args 可将原始格式中的额外命令行标志传递给转换器。请参阅alloy convert了解 extra-args 工作原理的更多详细信息。