zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/monitoring/thresholds.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "zabbix_manager/monitoring/expressions"
+
+class ZabbixManager
+  class Monitoring
+    # 先完整验证监控项和阈值，再生成不含远端副作用的触发器定义。
+    # 不执行 item.get 或写请求；已有监控项的归属及创建必填字段由资源层继续核对。
+    # @api private
+    class Thresholds
+      DEFAULT_WINDOW = "5m"
+      DEFAULT_PRIORITY = 3
+      FUNCTIONS = %w[avg max min last].freeze
+      METRICS = { bandwidth: %i[inbound_bps outbound_bps], errors: %i[in_errors out_errors],
+                  packet_loss: [:packet_loss] }.freeze
+      MANAGED_TAGS = %w[managed_by interface metric zabbix_manager_id].freeze
+      CONFIG_KEYS = %i[metrics capacity_bps high_percent recovery_percent high recovery window
+                       recovery_window function description priority tags].freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # 复制原生 item 定义并绑定主机/接口；省略字段保留给资源层默认值与校验处理。
+      # @return [Hash{Symbol => Hash}] 按业务指标名称分组的监控项属性
+      def prepare_items(host, interface, definitions)
+        items = Validation.hash!(definitions, "items").to_h do |metric, attributes|
+          attributes = Validation.hash!(attributes, "item #{metric}")
+          Validation.item_key!(attributes[:key_])
+          attributes[:hostid] = host[:hostid]
+          attributes[:interfaceid] = interface[:interfaceid] if interface[:interfaceid]
+          attributes[:name] = attributes.fetch(:name, "#{interface[:name]} #{metric.to_s.tr('_', ' ')}")
+          Validation.text!(attributes[:name], "item #{metric} name")
+          [metric, attributes]
+        end
+        if items.values.map { |item| item[:key_] }.uniq.length != items.length
+          raise Invalid, "item key_ values must be unique within an interface"
+        end
+
+        items
+      end
+
+      # 高阈值任一方向超限即可告警；所有方向低于或等于恢复值才恢复。
+      # 初次预检可只检查结构；合并远端配置后必须校验完整监控项。
+      # @return [Hash{Symbol => Hash}] 包含表达式、恢复表达式及受管身份的写入属性
+      def prepare_triggers(host:, interface:, items:, thresholds:, validate_items: true)
+        Validation.host!(host)
+        Validation.hash!(thresholds, "thresholds").to_h do |metric, attributes|
+          config = self.class.validate_config!(metric, attributes)
+          selected = select_items(metric, config, items, validate_items: validate_items)
+          high, recovery = self.class.values(metric, config)
+          function = config.fetch(:function, "avg")
+          window = config.fetch(:window, DEFAULT_WINDOW)
+          description = config.fetch(:description, "#{interface[:name]} #{metric.to_s.tr('_', ' ')} high")
+          Validation.text!(description, "threshold #{metric} description")
+          keys = selected.map { |item| Validation.item_key!(item[:key_]) }
+          [metric, {
+            hostid: host[:hostid], description: description,
+            expression: expression(host[:host], keys, function, window, ">", high, "or"),
+            recovery_mode: 1,
+            recovery_expression: expression(host[:host], keys, function,
+                                            config.fetch(:recovery_window, window), "<=", recovery, "and"),
+            priority: Validation.priority!(config.fetch(:priority, DEFAULT_PRIORITY)), manual_close: 1,
+            tags: managed_tags(interface[:name], metric, config.fetch(:tags, [])),
+            managed_key: managed_key(interface, metric)
+          }]
+        end
+      end
+
+      def self.validate_config!(metric, attributes)
+        raise Invalid, "unsupported threshold #{metric}" unless METRICS.key?(metric)
+
+        config = Validation.hash!(attributes, "threshold #{metric}")
+        config.assert_valid_keys(*CONFIG_KEYS)
+        Validation.window!(config.fetch(:window, DEFAULT_WINDOW))
+        Validation.window!(config.fetch(:recovery_window, config.fetch(:window, DEFAULT_WINDOW)))
+        Validation.priority!(config.fetch(:priority, DEFAULT_PRIORITY))
+        unless FUNCTIONS.include?(config.fetch(:function, "avg"))
+          raise Invalid, "function must be one of #{FUNCTIONS.join(', ')}"
+        end
+
+        high, recovery = values(metric, config)
+        unless high.finite? && recovery.finite? && high.positive? && recovery >= 0 && recovery < high
+          raise Invalid, "#{metric} thresholds must be finite with recovery non-negative and lower than high"
+        end
+        if metric == :packet_loss && high > 100
+          raise Invalid, "packet_loss high must be at most 100 percent"
+        end
+
+        config
+      rescue ArgumentError => error
+        raise Invalid, error.message
+      end
+
+      def self.values(metric, config)
+        if metric == :bandwidth
+          capacity = Validation.number!(config[:capacity_bps], "bandwidth capacity_bps")
+          high = Validation.number!(config[:high_percent], "bandwidth high_percent")
+          recovery = Validation.number!(config[:recovery_percent], "bandwidth recovery_percent")
+          unless capacity.positive? && high.between?(0, 100) && recovery.between?(0, 100)
+            raise Invalid, "bandwidth capacity must be positive and percentages must be between 0 and 100"
+          end
+
+          [capacity * (high / 100), capacity * (recovery / 100)]
+        else
+          [Validation.number!(config[:high], "#{metric} high"),
+           Validation.number!(config[:recovery], "#{metric} recovery")]
+        end
+      end
+
+      private
+
+      def select_items(metric, config, items, validate_items:)
+        names = Validation.array!(config.fetch(:metrics, METRICS.fetch(metric)), "threshold metrics")
+        raise Invalid, "threshold #{metric} requires at least one item" if names.empty?
+
+        names.map do |name|
+          unless name.is_a?(String) || name.is_a?(Symbol)
+            raise Invalid, "threshold metric names must be strings or symbols"
+          end
+
+          item = items.fetch(name.to_sym) { raise Invalid, "threshold #{metric} requires item metric #{name}" }
+          validate_units!(metric, item) if validate_items
+          item
+        end
+      end
+
+      def validate_units!(metric, item)
+        if item.key?(:value_type) && !%w[0 3].include?(item[:value_type].to_s)
+          raise Invalid, "threshold #{metric} requires a numeric value_type"
+        end
+
+        case metric
+        when :bandwidth
+          TrafficItems.validate_bps!(item)
+        when :errors
+          steps = Validation.array!(item.fetch(:preprocessing, []), "error preprocessing")
+                            .map { |step| Validation.hash!(step, "error preprocessing step") }
+          rate_step = steps.any? { |step| step[:type].to_s == "10" }
+          explicit_rate = [item[:key_], item[:name]].join(" ").match?(/(?:\brate\b|[._]rate\b|per[._ -]?second)/i)
+          unless rate_step || explicit_rate
+            raise Invalid, "error metric #{item[:key_]} must represent a per-second rate"
+          end
+        when :packet_loss
+          raise Invalid, "packet loss metric #{item[:key_]} must use % units" unless item[:units] == "%"
+        end
+      end
+
+      def expression(host, keys, function, window, operator, threshold, joiner)
+        expressions = Expressions.new(@client, host)
+        keys.map { |key| expressions.compare(key, function, window, operator, threshold) }.join(" #{joiner} ")
+      end
+
+      def managed_tags(interface_name, metric, extra_tags)
+        tags = [
+          { tag: "managed_by", value: "zabbix_manager" },
+          { tag: "interface", value: interface_name },
+          { tag: "metric", value: metric.to_s }
+        ]
+        extra = Validation.array!(extra_tags, "threshold tags").map do |tag|
+          tag = Validation.hash!(tag, "threshold tag")
+          tag.assert_valid_keys(:tag, :value)
+          Validation.text!(tag[:tag], "threshold tag name")
+          raise Invalid, "threshold tag #{tag[:tag]} is reserved" if MANAGED_TAGS.include?(tag[:tag])
+          raise Invalid, "threshold tag value must be a string" unless tag.fetch(:value, "").is_a?(String)
+
+          { tag: tag[:tag], value: tag.fetch(:value, "") }
+        end
+        (tags + extra).uniq
+      end
+
+      def managed_key(interface, metric)
+        identity = interface[:line_id].presence || interface[:interfaceid].presence ||
+                   TrafficItems.interface_identity(interface[:name])
+        key = "interface:#{identity}:#{metric}"
+        raise Invalid, "managed_key is too long" if key.length > Triggers::MAX_MANAGED_KEY_LENGTH
+
+        key
+      end
+    end
+  end
+end

data/lib/zabbix_manager/monitoring/traffic_items.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  class Monitoring
+    # 精确匹配已发现接口，并证明流量项的方向与 bit/s 语义。
+    class TrafficItems
+      OCTET_OID = /\A\.?1\.3\.6\.1\.2\.1\.31\.1\.1\.1\.(6|10)(?:\.\d+)*\z/
+      LEGACY_OCTET_OID = /\A\.?1\.3\.6\.1\.2\.1\.2\.2\.1\.(10|16)(?:\.\d+)*\z/
+      SYMBOLIC_OCTET_OID = /\A(?:IF-MIB::)?if(?:HC)?(In|Out)Octets(?:\.\d+)*\z/
+      INTERFACE_TOKEN = /(?<![A-Za-z0-9\/._-])(?:[A-Za-z][A-Za-z_-]*)?\d+(?:[\/.:]\d+)*(?![A-Za-z0-9\/._-]|:\d)/
+
+      def self.interface_identity(value)
+        # 只归一已知厂商前缀；未知接口名的大小写和分隔符属于身份。
+        aliases = { "te" => /\A(?:ten[-_ ]?gigabit[-_ ]?ethernet|te)(\d[\d\/.:]*)\z/i,
+                    "gi" => /\A(?:gigabit[-_ ]?ethernet|gi)(\d[\d\/.:]*)\z/i,
+                    "eth" => /\A(?:ethernet|eth)(\d[\d\/.:]*)\z/i }
+        aliases.each do |prefix, pattern|
+          match = pattern.match(value)
+          return "#{prefix}#{match[1]}" if match
+        end
+        value
+      end
+
+      def self.counter_direction(value)
+        oid = value.to_s
+        oid = oid.delete_prefix("get[").delete_suffix("]") if oid.start_with?("get[") && oid.end_with?("]")
+        match = OCTET_OID.match(oid)
+        return match[1] == "6" ? :inbound : :outbound if match
+
+        symbolic = SYMBOLIC_OCTET_OID.match(oid)
+        return symbolic[1] == "In" ? :inbound : :outbound if symbolic
+
+        legacy = LEGACY_OCTET_OID.match(oid)
+        return unless legacy
+
+        legacy[1] == "10" ? :inbound : :outbound
+      end
+
+      # 匹配完整接口名称标记，包括子接口及常见厂商缩写。
+      # @api private
+      def self.interface_matches?(item, interface_name)
+        identity = interface_identity(interface_name)
+        [item["name"], item["key_"], item["snmp_oid"]].compact.any? do |field|
+          field.to_s.scan(INTERFACE_TOKEN).any? { |token| interface_identity(token) == identity }
+        end
+      end
+
+      def initialize(items)
+        @items = items
+      end
+
+      # 拒绝零匹配、多匹配和同一 itemid 同时充当两个方向；返回项仍须由调用方核对主机。
+      # @return [Hash] inbound、outbound 对应的符号键监控项属性
+      def for_interface(interface_name)
+        identity = self.class.interface_identity(interface_name)
+        candidates = @items.select do |item|
+          traffic_item?(item) && interface_item?(item, identity)
+        end
+        selected = %i[inbound outbound].to_h do |direction|
+          matches = candidates.select { |item| direction_item?(item, direction) }
+          unless matches.one?
+            raise Conflict, "expected one #{direction} traffic item for #{interface_name}, found #{matches.length}"
+          end
+
+          item = matches.first.deep_symbolize_keys
+          Validation.positive_id!(item[:itemid], "traffic itemid")
+          Validation.item_key!(item[:key_])
+          self.class.validate_bps!(item)
+          [direction, item]
+        end
+        if selected[:inbound][:itemid].to_s == selected[:outbound][:itemid].to_s
+          raise Conflict, "inbound and outbound traffic items must have distinct itemids"
+        end
+
+        selected
+      end
+
+      # bps 标签不足以证明原始 octet 计数的量纲；同时检查速率转换和乘数 8。
+      # @raise [Invalid] 单位或预处理不足以证明 bit/s 语义
+      def self.validate_bps!(item)
+        unless item[:units] == "bps"
+          raise Invalid, "traffic item #{item[:itemid] || item[:key_]} must use bps units"
+        end
+        return unless raw_counter?(item)
+
+        steps = Validation.array!(item.fetch(:preprocessing, []), "traffic preprocessing")
+                          .map { |step| Validation.hash!(step, "traffic preprocessing step") }
+        if steps.first&.dig(:type).to_s == "28"
+          oid, format = steps.first[:params].to_s.split("\n")
+          steps = steps.drop(1) if counter_direction(oid) && format == "0"
+        end
+        change_per_second = steps.count { |step| step[:type].to_s == "10" } == 1
+        multipliers = steps.select { |step| step[:type].to_s == "1" }
+        bits_multiplier = multipliers.one? && Validation.number!(multipliers.first[:params], "multiplier") == 8
+        return if change_per_second && bits_multiplier && steps.length == 2
+
+        raise Invalid,
+              "raw octet item #{item[:itemid] || item[:key_]} requires change-per-second and multiplier 8 preprocessing"
+      end
+
+      def self.raw_counter?(item)
+        counter_direction(item[:snmp_oid]) || item[:key_].to_s.match?(/if(?:hc)?(in|out)octets/i) ||
+          (%w[0 7].include?(item[:type].to_s) && item[:key_].match?(/\Anet\.if\.(in|out)\[/))
+      end
+      private_class_method :raw_counter?
+
+      private
+
+      def interface_item?(item, identity)
+        self.class.interface_matches?(item, identity)
+      end
+
+      def traffic_item?(item)
+        blob = [item["key_"], item["name"]].join(" ").downcase
+        return false if blob.match?(/error|discard|drop|packet|status|utilization|percentage|percent/)
+
+        self.class.counter_direction(item["snmp_oid"]) ||
+          blob.match?(/net\.if\.(in|out)(?:\[|\b)|ifhc(in|out)octets|inbound|outbound/)
+      end
+
+      def direction_item?(item, direction)
+        counter = self.class.counter_direction(item["snmp_oid"])
+        return counter == direction if counter
+
+        blob = [item["key_"], item["name"]].join(" ").downcase
+        inbound = blob.match?(/net\.if\.in\b|ifhcin|inbound/)
+        outbound = blob.match?(/net\.if\.out\b|ifhcout|outbound/)
+        direction == :inbound ? inbound && !outbound : outbound && !inbound
+      end
+    end
+  end
+end

data/lib/zabbix_manager/monitoring/validation.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class ZabbixManager
+  class Monitoring
+    # 监控输入的形状、数值和表达式边界；不做静默类型强制转换。
+    # 校验容器不代表授权；数值允许可解析的十进制字符串，ID 不接受浮点或布尔值。
+    # @api private
+    module Validation
+      ITEM_KEY = /\A[A-Za-z0-9_.-]+(?:\[(?:[A-Za-z0-9_.:,\/\- {}\#$]|"(?:[^"\\\r\n]|\\.)*")*\])?\z/
+      HOST_NAME = /\A[A-Za-z0-9 ._-]+\z/
+
+      module_function
+
+      def hash!(value, name)
+        raise Invalid, "#{name} must be a hash" unless value.is_a?(Hash)
+
+        value.deep_symbolize_keys
+      end
+
+      def array!(value, name)
+        raise Invalid, "#{name} must be an array" unless value.is_a?(Array)
+
+        value
+      end
+
+      # 字符串 "false" 不能作为真值启用提前终止等控制分支。
+      def boolean!(value, name)
+        raise Invalid, "#{name} must be true or false" unless value == true || value == false
+
+        value
+      end
+
+      def text!(value, name)
+        raise Invalid, "#{name} must be a non-empty string" unless value.is_a?(String) && value.present?
+
+        value
+      end
+
+      def positive_id!(value, name)
+        unless value.to_s.match?(/\A[1-9]\d*\z/) && (value.is_a?(Integer) || value.is_a?(String))
+          raise Invalid, "#{name} must be a positive integer"
+        end
+
+        value
+      end
+
+      def host!(host)
+        positive_id!(host[:hostid], "host.hostid")
+        text!(host[:host], "host.host")
+        raise Invalid, "host.host contains unsupported characters" unless HOST_NAME.match?(host[:host])
+      end
+
+      def item_key!(key)
+        text!(key, "item key_")
+        raise Invalid, "item key_ contains unsupported expression characters" unless ITEM_KEY.match?(key)
+
+        key
+      end
+
+      def number!(value, name)
+        number = BigDecimal(value.to_s)
+        raise Invalid, "#{name} must be finite" unless number.finite?
+
+        number
+      rescue ArgumentError, TypeError
+        raise Invalid, "#{name} must be a finite number"
+      end
+
+      def window!(window)
+        unless window.is_a?(String) && window.match?(/\A[1-9]\d*[smhdw]\z/)
+          raise Invalid, "window must use a positive Zabbix duration such as 5m or 1h"
+        end
+
+        window
+      end
+
+      def priority!(priority)
+        unless (priority.is_a?(Integer) || priority.is_a?(String)) && priority.to_s.match?(/\A[0-5]\z/)
+          raise Invalid, "priority must be an integer between 0 and 5"
+        end
+
+        priority.to_i
+      end
+
+      def format_number(number)
+        number.to_i == number ? number.to_i.to_s : number.to_s("F")
+      end
+    end
+  end
+end

data/lib/zabbix_manager/monitoring.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "zabbix_manager/monitoring/validation"
+require "zabbix_manager/monitoring/traffic_items"
+require "zabbix_manager/monitoring/thresholds"
+require "zabbix_manager/monitoring/line"
+require "zabbix_manager/monitoring/line_items"
+require "zabbix_manager/monitoring/line_plan"
+require "zabbix_manager/monitoring/line_lifecycle"
+require "zabbix_manager/monitoring/device"
+
+class ZabbixManager
+  # 网络设备、接口和线路监控编排。先验证整批输入，再按稳定身份执行远端操作。
+  class Monitoring
+    # @param manager [ZabbixManager] 共享认证客户端和资源对象
+    def initialize(manager)
+      @manager = manager
+      @thresholds = Thresholds.new(manager.client)
+      @workflow_mutex = Mutex.new
+    end
+
+    # 按技术主机名装配设备监控；名称引用在写入前通过 API 解析。
+    # 同一实例内串行执行工作流，远端写入没有数据库事务或跨进程原子性。
+    # @param device [Hash] 原生主机属性及 groups/templates、snmp、proxy_group、managed 等业务选项
+    # @return [Hash] hostid、enabled 和下次更新可传回的 managed 集合归属回执
+    # @raise [Invalid, Conflict] 输入无效、引用不唯一或不支持当前服务端版本
+    # @raise [ApiError, TransportError] 远端操作失败；超时后应先核查远端状态
+    def reconcile_device(device)
+      definition = Device.new(device)
+      @workflow_mutex.synchronize { definition.reconcile(@manager) }
+    end
+
+    # 先校验整批本地定义，再逐台对账；单台失败不掩盖其他设备的结果。
+    # @param devices [Array<Hash>] 设备定义，技术主机名必须唯一
+    # @param fail_fast [Boolean] true 时首个远端错误向上抛出
+    # @return [Array<Hash>] 每台设备的身份、status 和 result，或脱敏 error
+    # @raise [Invalid] 本地定义无效，此时整批尚未写入
+    def reconcile_devices(devices, fail_fast: false)
+      Validation.boolean!(fail_fast, "fail_fast")
+      reconcile_device_definitions(validate_devices!(devices), fail_fast: fail_fast)
+    end
+
+    # 线路预检在设备写入之前完成；线路发现依赖设备或模板产生的监控项。
+    # 模板/LLD 异步产生监控项，设备成功不代表对应线路已就绪。
+    # @param devices [Array<Hash>] 设备定义
+    # @param lines [Array<Hash>] 单端点线路定义；双端使用独立 line_id
+    # @param fail_fast [Boolean] true 时首个远端错误向上抛出
+    # @return [Hash] devices、lines 逐项结果和成功/失败/未知数量 summary
+    def reconcile_network(devices:, lines:, fail_fast: false)
+      Validation.boolean!(fail_fast, "fail_fast")
+      line_definitions = validate_lines!(lines)
+      device_definitions = validate_devices!(devices)
+      results = {
+        devices: reconcile_device_definitions(device_definitions, fail_fast: fail_fast),
+        lines: reconcile_line_definitions(line_definitions, fail_fast: fail_fast)
+      }
+      results.merge(summary: batch_summary(results))
+    end
+
+    # 只读解析主机和监控项，预览实际触发器属性及按类型引用的依赖。
+    # ICMP 是 Zabbix server/proxy 对目标的检查，不能证明专线两端的转发路径。
+    # @param attributes [Hash] 单端点 line_id、host、interface_name、capacity_mbps 及可选监控配置
+    # @return [Hash] hostid、line_id、itemids、triggers、dependencies 和可选 icmp_item
+    # @raise [Invalid, Conflict] 阈值、量纲、项目选择或管理归属无法确定
+    # @raise [ApiError, TransportError] 远端发现失败，此方法从不写入
+    def plan_line(attributes)
+      prepare_line(Line.new(attributes), {})
+    end
+
+    # 对账一个端点，确认所需触发器后停用该线路不再需要的受管类型。
+    # 同一实例串行执行；多步远端写入不具备事务回滚或跨进程原子性。
+    # @param attributes [Hash] 与 plan_line 相同的线路定义
+    # @return [Hash] 主机、接口、line_id、按指标分类的 itemids 和 triggerids
+    # @raise [Invalid, Conflict] 预检失败，此时没有线路写入
+    # @raise [ApiError, TransportError] 远端失败；已确认的步骤保留，传输失败可能已提交
+    def reconcile_line(attributes)
+      line = Line.new(attributes)
+      @workflow_mutex.synchronize { apply_line(prepare_line(line, {})) }
+    end
+
+    # 先预检整批本地输入和远端发现，再逐端点执行，保留失败与结果未知的区别。
+    # @param lines [Array<Hash>] line_id 唯一的端点定义；双端线路使用两个不同 line_id
+    # @param fail_fast [Boolean] 遇到首个远端失败时向上抛出
+    # @return [Array<Hash>] 每个端点的 status、result 或脱敏 error
+    # @raise [Invalid] 本地定义或解析后的目标重复
+    def reconcile_lines(lines, fail_fast: false)
+      Validation.boolean!(fail_fast, "fail_fast")
+      reconcile_line_definitions(validate_lines!(lines), fail_fast: fail_fast)
+    end
+
+    # 查询端点的受管触发器；人工触发器及其他管理方的同名对象不在结果中。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份，或 plan_line 返回的自动身份
+    # @return [Array<Hash>] 原生 trigger.get 对象，包括 tags、items、状态及表达式
+    # @raise [Invalid, Conflict, ProtocolError] 输入无效或远端管理身份不唯一
+    def line_triggers(hostid:, line_id:)
+      LineLifecycle.new(@manager, hostid, line_id).owned
+    end
+
+    # 停用一个端点的全部受管触发器；不删除触发器或共享 ICMP 监控项。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份
+    # @return [Array<Integer>] 已确认停用的触发器 ID；没有受管对象时为空
+    # @raise [ApiError, TransportError] 写入失败或结果尚未确认
+    def disable_line(hostid:, line_id:)
+      lifecycle = LineLifecycle.new(@manager, hostid, line_id)
+      @workflow_mutex.synchronize { lifecycle.disable }
+    end
+
+    # 按该端点的触发器 ID 在服务端过滤问题，再应用数量上限。
+    # Zabbix problem.get 的 recent 范围受服务器问题保留配置影响，不代表完整事件归档。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份
+    # @param time_from [Integer, Time] 查询起点（Unix 秒或 Time）
+    # @param time_till [Integer, Time] 查询终点，默认为当前时间
+    # @param limit [Integer] 最大记录数，1..1000；多读取一条以判定截断
+    # @return [Hash] problems、truncated、time_from、time_till 和 limit
+    # @raise [Invalid, ProtocolError] 范围无效或响应超出目标线路
+    def line_problems(hostid:, line_id:, time_from:, time_till: Time.now, limit: 100)
+      LineLifecycle.new(@manager, hostid, line_id).problems(time_from: time_from, time_till: time_till, limit: limit)
+    end
+
+    # 接口更新只增改，不自动删除远端对象；所有本地校验在首个写入之前完成。
+    # @param attributes [Hash] host、interface、按名称分组的原生 items 和 thresholds
+    # @return [Hash] hostid、interface、itemids 和 triggerids
+    # @raise [Invalid, Conflict] 输入、量纲或资源归属无效
+    # @raise [ApiError, TransportError] 远端失败；已经确认的早期步骤不会被回滚
+    def reconcile_interface(attributes)
+      input = Validation.hash!(attributes, "interface monitoring")
+      input.assert_valid_keys(:host, :interface, :items, :thresholds)
+      supplied_host = Validation.hash!(input[:host], "host")
+      Validation.host!(supplied_host)
+      interface = Validation.hash!(input[:interface], "interface")
+      interface.assert_valid_keys(:name, :interfaceid)
+      Validation.text!(interface[:name], "interface.name")
+      Validation.positive_id!(interface[:interfaceid], "interface.interfaceid") if interface.key?(:interfaceid)
+      items = @thresholds.prepare_items(supplied_host, interface, input.fetch(:items, {}))
+      triggers = @thresholds.prepare_triggers(
+        host: supplied_host, interface: interface, items: items, thresholds: input.fetch(:thresholds, {}),
+        validate_items: false
+      )
+      host = resolve_host(supplied_host, {})
+      ids = @manager.items.upsert_many(items.values) do |effective|
+        # 读取已有配置后再次校验最终量纲和数值类型，仍在首个 item 写入之前。
+        triggers = @thresholds.prepare_triggers(
+          host: supplied_host, interface: interface, items: items.keys.zip(effective).to_h,
+          thresholds: input.fetch(:thresholds, {})
+        )
+      end
+      itemids = items.keys.zip(ids).to_h
+      triggerids = triggers.transform_values { |trigger| @manager.triggers.upsert_for_host(trigger) }
+      { hostid: host[:hostid].to_i, interface: interface[:name], itemids: itemids, triggerids: triggerids }
+    end
+
+    private
+
+    def validate_devices!(devices)
+      definitions = Validation.array!(devices, "devices").map { |device| Device.new(device) }
+      validate_unique!(definitions.map(&:identity), "device host")
+      definitions
+    end
+
+    def validate_lines!(lines)
+      definitions = Validation.array!(lines, "lines").map { |attributes| Line.new(attributes) }
+      validate_unique!(definitions.map(&:identity), "line_id or host/interface")
+      definitions
+    end
+
+    def validate_unique!(identities, name)
+      duplicate = identities.tally.find { |_identity, count| count > 1 }
+      raise Invalid, "duplicate #{name}" if duplicate
+    end
+
+    def reconcile_device_definitions(devices, fail_fast:)
+      devices.map do |device|
+        identity = device.safe_identity
+        result = @workflow_mutex.synchronize { device.reconcile(@manager) }
+        { status: :ok, device: identity, result: result }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
+
+        failure_result(:device, identity, error, writing: true)
+      end
+    end
+
+    # 先完成线路发现，防止两个不同候选主机名解析到同一触发器后互相覆盖。
+    def reconcile_line_definitions(lines, fail_fast:)
+      cache = {}
+      prepared = lines.map do |line|
+        { line: line, plan: prepare_line(line, cache) }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
+
+        { line: line, failure: failure_result(:line, line.safe_identity, error) }
+      end
+      identities = prepared.filter_map do |entry|
+        plan = entry[:plan]
+        [plan[:hostid], plan[:line_id]] if plan
+      end
+      validate_unique!(identities, "line target")
+      prepared.map do |entry|
+        next entry[:failure] if entry[:failure]
+
+        { status: :ok, result: @workflow_mutex.synchronize { apply_line(entry[:plan]) } }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
+
+        failure_result(:line, entry[:line].safe_identity, error, writing: true)
+      end
+    end
+
+    def prepare_line(line, cache)
+      host = resolve_host(line.host_reference, cache)
+      source_items = cache[[:items, host[:hostid].to_s]] ||=
+        @manager.items.monitored_traffic_candidates(host[:hostid])
+      resolver = LineItems.new(@manager.items)
+      selected = resolver.resolve(line, source_items, hostid: host[:hostid])
+      icmp_item = resolver.icmp_plan(host[:hostid], line.reachability_target) if line.reachability_target
+      plan = LinePlan.new(@manager.client, line, host, selected, icmp_item).to_h
+      lifecycle = LineLifecycle.new(@manager, plan[:hostid], plan[:line_id])
+      lifecycle.validate_ownership!(lifecycle.inventory, plan[:triggers].values.pluck(:managed_key))
+      plan
+    end
+
+    def apply_line(plan)
+      lifecycle = LineLifecycle.new(@manager, plan[:hostid], plan[:line_id])
+      existing = lifecycle.inventory
+      desired_keys = plan[:triggers].values.pluck(:managed_key)
+      lifecycle.validate_ownership!(existing, desired_keys)
+      itemids = plan[:itemids].dup
+      if plan[:icmp_item]
+        itemids[:reachability] = LineItems.new(@manager.items).ensure_icmp(plan[:icmp_item])
+      end
+      triggerids = {}
+      plan[:triggers].each do |kind, attributes|
+        dependencies = plan[:dependencies].fetch(kind).map { |dependency| { triggerid: triggerids.fetch(dependency) } }
+        triggerids[kind] = @manager.triggers.upsert_for_host(attributes.merge(dependencies: dependencies))
+      end
+      lifecycle.retire(existing, desired_keys)
+      plan.slice(:hostid, :host, :interface, :line_id).merge(itemids: itemids, triggerids: triggerids)
+    end
+
+    def resolve_host(reference, cache)
+      host = cache[[:host, reference]] ||= @manager.hosts.resolve(reference)
+      reference.is_a?(Hash) ? host.merge(hostid: reference[:hostid]) : host
+    end
+
+    def failure_result(kind, identity, error, writing: false)
+      unknown = error.is_a?(ResultUnknown) || (writing && error.is_a?(TransportError))
+      {
+        status: unknown ? :unknown : :error,
+        kind => identity,
+        error: { class: error.class.name, message: LogSanitizer.sanitize(error.message) }
+      }
+    end
+
+    def batch_summary(results)
+      results.transform_values do |entries|
+        statuses = entries.map { |entry| entry[:status] }.tally
+        { total: entries.length, succeeded: statuses.fetch(:ok, 0),
+          failed: statuses.fetch(:error, 0), unknown: statuses.fetch(:unknown, 0) }
+      end
+    end
+  end
+end