Skip to content

feat(workflow): trace standalone workflow steps and parallel branches (issue #322) - #381

Open
konlue wants to merge 1 commit into
agentic-ai-java:mainfrom
konlue:feat/issue322-workflow-step-tracing
Open

konlue wants to merge 1 commit into
agentic-ai-java:mainfrom
konlue:feat/issue322-workflow-step-tracing

Conversation

@konlue

@konlue konlue commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Describe what this PR does / why we need it

Issue #322 asks for tracing on standalone Workflow steps and parallel branches. The workflow engine had no observability seam at all, and the micrometer trace package lives in a module the workflow core deliberately does not depend on. This PR wires step-level tracing through the neutral lifecycle contract and adds a micrometer bridge where both sides are visible.

The two-layer design

The workflow core now emits the neutral lifecycle events of the agent-api contract — LifecycleStage.WORKFLOW_STEP with StageEntered/StageExited — through an opt-in observer list on WorkflowAgent.Builder. It gains no micrometer dependency and no Graph/Loop dependency; with no observers, execution behavior is preserved exactly. The bridge lives in the agent-framework, which already sees both worlds: it gains a workflow-core dependency (acyclic) and ships WorkflowStepObservationObserver, translating the events into argi.agent.workflow.step spans on the shared AgentTracer from #131, following the established cross-agent naming conventions.

Emission semantics

Every executed step — Agent, Tool, Condition, Loop body, Parallel branch, Subflow — emits exactly one paired enter/exit on its executing thread. Retries fold into a single step-level exit (the issue's "each step ends exactly once"), a suspension exits successfully because handing off control is not a failure (resume-span fragments are issue #324's scope, stated as a boundary), and cancellation or failure exits with a failure reason. Parallel branches attribute their spans on the branch worker thread regardless of completion order — the fan-in merge still happens in declaration order and is untouched. The workflow run identity travels as the event's invocation id, sourced from the trusted run id, so spans stay correlatable without inheriting anything between independent runs. A parallelExecutor builder seam (default ForkJoinPool.commonPool, unchanged) exists purely so tests can drive deterministic branch interleaving.

The bridge details

WorkflowStepObservationObserver pairs enter/exit through a per-thread LIFO stack, which satisfies the "close on the starting thread" contract for nested sequences, loop bodies, condition branches and parallel branch workers alike. The trace vocabulary gains the WORKFLOW_STEP operation (argi.agent.workflow.step), a high-cardinality argi.agent.step.id key and a failure() marker on AgentTraceSpan for lifecycle exits that carry only a reason string — the event contract has no throwable, so the error-type key stays unset by design. With a disabled tracer the observer still receives events but creates no observation.

Testing

WorkflowStepLifecycleTest (workflow core) drives deterministic scenarios with a recording observer: paired LIFO emission over a sequence, once-only exits under retry, cancellation and suspension (with the resume not double-exiting), reversed parallel completion order gated by latches with correct branch attribution and worker-thread identity, loop iteration pairs including the container, and zero event inheritance between two independent runs. WorkflowStepObservationObserverTest (agent framework) asserts the span name, step id, run id, success and outcome keys on the micrometer side, including the failing path. The NOOP acceptance is covered by the untouched existing workflow tests (72/72 in workflow core), and the graph-core (593 run, known Windows baseline) and agent-framework (1420 run, same baseline) regressions are unchanged; checkstyle and spring-javaformat are clean.

Fixes #322

… (issue agentic-ai-java#322)

The workflow engine had no observability seam at all, and the micrometer
trace package lives in a module the workflow core deliberately does not
depend on. The engine now emits the neutral lifecycle events of the
agent-api contract (LifecycleStage.WORKFLOW_STEP, StageEntered/Exited)
through an opt-in observer list on WorkflowAgent.Builder - no micrometer
dependency, no Graph/Loop dependency, and with no observers the
execution behavior is preserved exactly.

Each executed step (Agent, Tool, Condition, Loop body, Parallel branch,
Subflow) emits exactly one paired enter/exit on its executing thread:
retries fold into a single step exit, a suspension exits successfully
(hand-off is not a failure; resume fragments are issue agentic-ai-java#324's scope),
and cancellation or failure exits with a failure reason. Parallel
branches attribute their spans on the branch worker thread regardless
of completion order, and a parallelExecutor builder seam (default
ForkJoinPool.commonPool, unchanged) lets tests drive deterministic
interleaving.

The bridge to micrometer lives where both sides are visible: the
agent-framework gains a workflow-core dependency and
WorkflowStepObservationObserver translates the events into
argi.agent.workflow.step spans on the shared AgentTracer, pairing
enter/exit through a per-thread LIFO stack. The trace vocabulary gains
the WORKFLOW_STEP operation, a high-cardinality step.id key and a
failure() marker for lifecycle exits that carry only a reason string.

Deterministic tests cover paired LIFO emission, once-only exits under
retry/cancellation/suspension, reversed parallel completion order with
correct branch attribution and worker-thread identity, loop iterations,
and zero inheritance between independent runs; the adapter tests assert
span name, step id, run id, success and outcome keys.
@konlue

konlue commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

Note on the failing build job: it fails in pnpm --dir argi-studio/agent-chat-ui audit --prod, which queries the vulnerability database live. This surfaced today — the same step passed on main on 2026-11-19 (run 44558278320) and fails identically on the unrelated #370 branch (run 44882915599), while every Java-side job (test, check-style, format, license, linter, secret) is green on this PR. It is the studio UI's dependency disclosure, not this change; the lockfile fix belongs to the argi-studio maintainers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Task][P1] 为独立 Workflow 的步骤与并行分支接入追踪

1 participant