Class BaseObservabilityFlowMetrics

java.lang.Object
cloud.opencode.base.flow.observability.BaseObservabilityFlowMetrics
All Implemented Interfaces:
FlowMetrics
public final class BaseObservabilityFlowMetrics extends Object implements FlowMetrics
FlowMetrics adapter that forwards every event into a MetricRegistry from opencode-base-observability. Used implicitly when that module is present on the runtime classpath; see FlowMetricsFactory.create(). FlowMetrics 适配器，把每次事件转发到 opencode-base-observability 的 MetricRegistry；当该模块在运行时类路径出现时由 FlowMetricsFactory.create() 隐式启用。

Emitted metrics:

  • flow.instance.started — counter, tag flow_key
  • flow.instance.completed — counter, tags flow_key, status
  • flow.task.created — counter, tags flow_key, step_id
  • flow.task.completed — counter, tags flow_key, step_id, outcome
  • flow.operation.duration — timer, tag type
  • flow.todo.size — gauge (no tags); driven by updateTodoSize(int)
Since:
JDK 25, opencode-base-flow V1.0.5
Author:
Leon Soo

  • Field Details

    • MAX_TAG_CARDINALITY

      public static final int MAX_TAG_CARDINALITY
      Hard ceiling on the distinct flow_key tag-values this adapter will ever emit. Above this cap the tag is replaced with OVERFLOW_TAG to deny metric-cardinality DoS via attacker- controlled flowKeys / stepIds. 单个指标允许出现的 flow_key（或 step_id）唯一值上限；超过转入 _overflow_ 桶。
      See Also:

    • OVERFLOW_TAG

      public static final String OVERFLOW_TAG
      Sentinel tag value used when the per-tag cardinality cap is exceeded.
      See Also:

  • Constructor Details

    • BaseObservabilityFlowMetrics

      public BaseObservabilityFlowMetrics(MetricRegistry registry)
      Constructs an adapter around the given registry. 围绕给定 registry 构造适配器。
      Parameters:
      registry - the registry — 指标注册表
      Since:
      JDK 25, opencode-base-flow V1.0.5

  • Method Details

    • registry

      public MetricRegistry registry()
      Returns the underlying registry (visible for tests and host introspection). 返回底层 registry（用于测试 / 宿主探测）。
      Returns:
      the registry — 指标注册表
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • recordInstanceStarted

      public void recordInstanceStarted(String flowKey)
      Description copied from interface: FlowMetrics
      Records that a new flow instance has started. 记录一次流程实例启动。
      Specified by:
      recordInstanceStarted in interface FlowMetrics
      Parameters:
      flowKey - business flow key — 业务 key

    • recordInstanceCompleted

      public void recordInstanceCompleted(String flowKey, InstanceStatus finalStatus)
      Description copied from interface: FlowMetrics
      Records that a flow instance has reached a terminal state. 记录一次流程实例达到终态。
      Specified by:
      recordInstanceCompleted in interface FlowMetrics
      Parameters:
      flowKey - business flow key — 业务 key
      finalStatus - the terminal status — 终态状态

    • recordTaskCreated

      public void recordTaskCreated(String flowKey, String stepId)
      Description copied from interface: FlowMetrics
      Records that a PENDING task has been created. 记录一次 PENDING 任务创建。
      Specified by:
      recordTaskCreated in interface FlowMetrics
      Parameters:
      flowKey - business flow key — 业务 key
      stepId - step id — 节点 ID

    • recordTaskCompleted

      public void recordTaskCompleted(String flowKey, String stepId, TaskOutcome outcome)
      Description copied from interface: FlowMetrics
      Records that a task has been completed (approved / rejected / canceled). 记录一次任务完成（同意 / 驳回 / 取消）。
      Specified by:
      recordTaskCompleted in interface FlowMetrics
      Parameters:
      flowKey - business flow key — 业务 key
      stepId - step id — 节点 ID
      outcome - final outcome (nullable when canceled) — 最终结果（取消时为 null）

    • recordOperationDuration

      public void recordOperationDuration(String type, Duration elapsed)
      Description copied from interface: FlowMetrics
      Records the wall-clock elapsed time of a single operation. 记录一次操作的墙钟耗时。
      Specified by:
      recordOperationDuration in interface FlowMetrics
      Parameters:
      type - operation type (start / approve / reject / vote / addSign / withdraw / transfer / circulate / terminate) — 操作类型
      elapsed - elapsed duration — 耗时

    • updateTodoSize

      public void updateTodoSize(int size)
      Description copied from interface: FlowMetrics
      Updates the gauge for the current todo-queue size of an observed user (or aggregate, depending on the host application). A negative value is a sentinel meaning "clear / reset to zero". 更新某用户（或聚合）的当前待办队列大小 gauge。传 -1 表示"清零"。
      Specified by:
      updateTodoSize in interface FlowMetrics
      Parameters:
      size - current size (or -1 to clear) — 当前大小（-1 表示清零）

    • todoSizeMetricId

      public static MetricId todoSizeMetricId()
      Returns the metric id used for the flow.todo.size gauge. Exposed so callers can locate the gauge in the registry snapshot. 返回 flow.todo.size gauge 的 MetricId，供调用方在 snapshot 中定位。
      Returns:
      the metric id — 指标 ID
      Since:
      JDK 25, opencode-base-flow V1.0.5