[dgafka]

Why is this change proposed?

Why

Important

Some span names, statuses and attributes change for existing tracing and OpenTelemetry users. Dashboards or alerts keyed on the old values need updating — see Before / after.

An application can now dump its whole message flow as a graph (Enterprise), and every feature that shows a flow — core tracing, OpenTelemetry, flow tracking and the graph — is proved against one shared catalogue of flows. Before, each feature had its own tests over its own model, so they drifted: a flow could be traced correctly yet stored wrongly by flow tracking, or be missing from the graph, with no test noticing.

• A catalogue scenario performs an action (send a command, run a consumer) and states the expected outcome once, as a tree of core tracing spans. Each feature adapts that expectation to its own model, so a scenario added once is checked by all four.
• The catalogue holds 85 core scenarios and 10 cross-module ones (database channels, dead letter, outbox, event-store projections, multi-tenancy). Writing them surfaced the behaviour changes below.

Before / after

Situation	Before	After
Projection trigger, reset, backfill, rebuild, initialize, delete	Untraced: replayed handler spans had no parent, and flow tracking stored nothing	Each starts its own flow, e.g. rebuild orders with ecotone.projection.operation
Polling projection, or scheduled endpoint without a request channel	receive projecting_manager_handler:<name> / receive nullChannel	poll <endpointId>
Message replayed from the dead letter or forwarded by the outbox	The relayed send was missing from the stored flow; a batch to a high-throughput channel started a new trace	Stored as a step of the original flow, each forwarded message continuing its own trace
Send that succeeds on a send retry; route held back by the message collector	Error span; ecotone.route.undelivered	Ok span; ecotone.route.collected

Example

$graph = $messagingSystem->getMessageFlowGraph();
echo $graph->toMermaid();

bin/console ecotone:flow:dump --format=mermaid   # or --format=json

For an application whose OrderService::place() command handler publishes OrderWasPlaced, handled asynchronously by Notifications and by an order_list projection, next to an order.status query handler, the dump renders as:

flowchart LR
    subgraph n1 ["Projection: order_list"]
        n8["Event Handler<br/>OrderListProjection::whenOrderPlaced"]
    end
    n0[("Channel<br/>notifications")]
    n2["Command Handler<br/>OrderService::place"]
    n3>"PlaceOrder"]
    n4["Query Handler<br/>OrderService::status"]
    n5{{"order.status"}}
    n6["Event Handler<br/>Notifications::whenOrderPlaced"]
    n7(["OrderWasPlaced"])
    n3 --> n2
    n5 --> n4
    n7 --> n0
    n0 ==>|"async"| n6
    n7 --> n8
    n2 -.->|"emits (publish)"| n7

Loading

An asynchronous handler sits behind its channel, in the order the message travels. The emitted event is inferred from the handler's source ($eventBus->publish(...)), shown as a dotted edge.

Description of Changes

Message flow graph (Enterprise)

ecotone:flow:dump and getMessageFlowGraph() draw buses, handlers, channels, aggregates, sagas, projections, interceptors, splitters, transformers, orchestrators and distributed routes. Without a licence the console command is not registered, and getMessageFlowGraph() throws a LicensingException.

Tracing and flow tracking

• Dynamic consistency boundary spans (Decision Models:, Conditional Append:) moved from OpenTelemetry into core tracing, so flow tracking records them too.
• The tracing channel interceptor runs last, so a send span is recorded only once the message reached its channel. A route whose message is filtered out is marked undelivered, and flow tracking no longer waits for it.
• Projection lifecycle operations run through endpoints (ProjectionOperations), so tracing and flow tracking wrap them like any other entry point. The console commands and FlowTestSupport::triggerProjection(), resetProjection(), initializeProjection() and deleteProjection() go through them.
• The dead letter replay and the outbox forwarder store their relayed sends through a FlowTrackingScope seam: TraceRecordingInterceptor when flow tracking is on, a pass-through otherwise.

Start reading at packages/Ecotone/src/Test/Flow/FlowScenarioCatalogue.php, then one suite: packages/Ecotone/tests/Tracing/TracingFlowConformanceTest.php.

Known gaps, left out deliberately

• A projection's own #[ProjectionInitialization], #[ProjectionDelete] and #[ProjectionReset] hooks run inside the operation span, without spans of their own.
• Each forwarding or scheduled poll is stored as its own one-span flow.
• An orchestrator gateway's steps are decided at runtime, so the graph cannot draw them; the graph check skips that one scenario.

Pull Request Contribution Terms

• I have read and agree to the contribution terms outlined in CONTRIBUTING.