Repository navigation
Conversation
… (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.
Contributor
Author
|
Note on the failing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_STEPwithStageEntered/StageExited— through an opt-in observer list onWorkflowAgent.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 shipsWorkflowStepObservationObserver, translating the events intoargi.agent.workflow.stepspans on the sharedAgentTracerfrom #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
parallelExecutorbuilder seam (defaultForkJoinPool.commonPool, unchanged) exists purely so tests can drive deterministic branch interleaving.The bridge details
WorkflowStepObservationObserverpairs 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 theWORKFLOW_STEPoperation (argi.agent.workflow.step), a high-cardinalityargi.agent.step.idkey and afailure()marker onAgentTraceSpanfor 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