You can't attach a debugger in production
A debugger shows an operation from the inside — but you can't attach one in production, and a live run offers nothing to grab onto.
During development a debugger freezes execution at any step: you see the arguments, the intermediate values, and what will be passed on. In production that's impossible — you can't halt the process for a single request, and a rare input is hard to reproduce. Nor can you watch a run on the fly: the chain of calls lives in the call stack, its intermediate values in local variables, and the moment a call returns, all of it disappears. Logs preserve only pre-selected values; a technical trace sees the calls and their duration but doesn't know which of them are business steps or which intermediate values between them matter. The cause has to be guessed from indirect clues.
The data exists at runtime — a debugger proves it. What's missing is something else: a boundary, known in advance, around the run and around each of its steps, one you can attach online observation to — without stopping the process.
{ validated_items: 3 } · all values visiblepause at any step — the whole state is visible
can't stop — the middle is invisible
The run's boundaries are already set by the architecture
To observe a run as a whole, it needs a precise boundary — and so does each of its steps.
In AOA an operation is an Action with an external boundary Params → Result. It's run by the machine — the AOA engine that executes an Action and knows in advance where the run begins and ends. Inside, the path is split into Aspects, each with its own intermediate state, state. An Aspect receives a snapshot of the previous state and returns its own new one — which fully replaces the previous state rather than augmenting it. So everything the following steps need, the Aspect carries forward explicitly, and nothing leaks between steps on its own; @result_* checks the output right at the boundary. These boundaries are not an observation tool but the very structure of the operation; yet they are exactly what gives the known-in-advance points where each step's input, output, and state are visible.
At any moment the machine knows the run's frame and its entire contractual path: what entered each Aspect and what state came out. The observable "single run" artifact is already assembled by the architecture itself — all that remains is to let it out.
{ }{ validated_items: 3 }{ validated_items: 3 }{ …, reservation_id: 'res_42' }{ …, reservation_id: 'res_42' }{ …, payment_id: 'pay_91' }Online debug: a live run seen from the outside
Since the boundaries are known, the machine emits an event at each one — and an external observer assembles them into a live picture of the run.
At the external boundary you see the actual Params and Result; at each internal one, the incoming and outgoing state, the duration, and any error. The machine knows all of these points and automatically emits lifecycle events; a plugin receives them from the outside and builds an online projection of a specific run — a tree of steps with real inputs, outputs, errors, and timing. The same in development, in tests, and in production — with no logging calls, manual timers, or tracing code inside the business methods.
This is not an attached debugger or a stopped process, but its safe online projection. The observer sees only what the contract permits: sensitive fields stay opaque, and a failure of the plugin itself is isolated and does not change the operation's result. This is exactly what Action X-Ray is.
- start · Params
- validate · state → state′ · 0.4 ms
- reserve · state′ → state″ · 12 msopaque
- charge · error · 3 ms
- finish · Result · 15 ms
The plugin is handed to the machine at creation — the business methods stay untouched:
plugin = OpenTelemetryPlugin( tracer_provider=tracer_provider, logger_provider=logger_provider, service_name="checkout-service",)# The plugin lives outside the Action; business methods stay untouched.machine = ActionProductMachine(plugins=[plugin])result = await machine.run(Context(), CreateOrderAction(), params)In a test — the same x-ray
The same online snapshot is available in a test too: TestBench runs the same operation through the same machine.
TestBench does not create a special test-only visibility — it runs the same Action through the same machine and the same boundaries. Only the outside world changes: instead of the production Context, Resources, and gateway, their test implementations are used, while the roles, pipeline, checkers, and the assembly of the Result stay real. The operation can be run in full or stopped at a single boundary — an Aspect, summary, or compensator — without special hooks in the business code.
A test verifies the same projection that's available in production: not only the final Result, but any intermediate state. What changes is the reality around the operation, not the operation itself or the way it's observed.
roles · pipeline · checkers · Result assemblyone and the same online projectionThe same Action through TestBench — in full or at a single boundary:
inventory = AsyncMock(spec=InventoryGateway)inventory.reserve.return_value = "res_42"bench = TestBench().with_user( user_id="customer", roles=(CustomerRole,)).with_mocks({InventoryGateway: inventory})# The whole operation — same machine, same boundariesresult = await bench.run(CreateOrderAction(), params, rollup=False)# Or stop at a single boundary and inspect its statestate_after = await bench.run_aspect( CreateOrderAction(), "reserve_aspect", params=params, state={"validated_items": 3},)assert state_after["reservation_id"] == "res_42"Online debug becomes a property of the architecture
AOA sets the external boundary of an Action, the internal boundaries of its Aspects, and turns intermediate state into a contract. During a run, those same boundaries become the coordinate system for lifecycle events — and the visibility that used to appear only under a debugger or after manual instrumentation is now available online for every execution, including production, with no infrastructure code inside the operation.