Interface FlowMetrics

All Known Implementing Classes:
BaseObservabilityFlowMetrics, NoOpFlowMetrics
public interface FlowMetrics
Engine-facing metrics façade — v4 §9.1. 引擎侧指标外观 —— v4 §9.1。

The flow engine emits five low-cardinality counters / timers / gauges via this interface. The default implementation is NoOpFlowMetrics (zero cost, no dependencies). When opencode-base-observability is on the runtime classpath, FlowMetricsFactory.create() returns BaseObservabilityFlowMetrics, which forwards every call into a MetricRegistry.

流程引擎通过本接口对外发射 5 类低基数 counter / timer / gauge。默认实现为 NoOpFlowMetrics（零开销 / 零依赖）；当 opencode-base-observability 出现在运行时类路径上，FlowMetricsFactory.create() 返回的 BaseObservabilityFlowMetrics 会把每一次调用转发到 MetricRegistry。

Tag-cardinality discipline: implementations must only use the static set of tag values produced by the engine (flow_key, step_id, outcome name, operation type) — never user-supplied free-text — to keep downstream backends bounded.

标签基数纪律：实现必须只使用引擎产出的静态标签集合 （flow_key、step_id、outcome 名、operation 类型），不得把用户自由文本 当作标签值，以保证下游后端基数有界。

Since:
JDK 25, opencode-base-flow V1.0.5
Author:
Leon Soo

  • Method Details

    • recordInstanceStarted

      void recordInstanceStarted(String flowKey)
      Records that a new flow instance has started. 记录一次流程实例启动。
      Parameters:
      flowKey - business flow key — 业务 key
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • recordInstanceCompleted

      void recordInstanceCompleted(String flowKey, InstanceStatus finalStatus)
      Records that a flow instance has reached a terminal state. 记录一次流程实例达到终态。
      Parameters:
      flowKey - business flow key — 业务 key
      finalStatus - the terminal status — 终态状态
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • recordTaskCreated

      void recordTaskCreated(String flowKey, String stepId)
      Records that a PENDING task has been created. 记录一次 PENDING 任务创建。
      Parameters:
      flowKey - business flow key — 业务 key
      stepId - step id — 节点 ID
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • recordTaskCompleted

      void recordTaskCompleted(String flowKey, String stepId, TaskOutcome outcome)
      Records that a task has been completed (approved / rejected / canceled). 记录一次任务完成（同意 / 驳回 / 取消）。
      Parameters:
      flowKey - business flow key — 业务 key
      stepId - step id — 节点 ID
      outcome - final outcome (nullable when canceled) — 最终结果（取消时为 null）
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • recordOperationDuration

      void recordOperationDuration(String type, Duration elapsed)
      Records the wall-clock elapsed time of a single operation. 记录一次操作的墙钟耗时。
      Parameters:
      type - operation type (start / approve / reject / vote / addSign / withdraw / transfer / circulate / terminate) — 操作类型
      elapsed - elapsed duration — 耗时
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • updateTodoSize

      void updateTodoSize(int size)
      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 表示"清零"。
      Parameters:
      size - current size (or -1 to clear) — 当前大小（-1 表示清零）
      Since:
      JDK 25, opencode-base-flow V1.0.5