Skip to content

Add comprehensive execution tracing#177

Merged
mxgrey merged 56 commits intomainfrom
improved_tracing
Mar 5, 2026
Merged

Add comprehensive execution tracing#177
mxgrey merged 56 commits intomainfrom
improved_tracing

Conversation

@mxgrey
Copy link
Contributor

@mxgrey mxgrey commented Mar 4, 2026

This PR introduces a major enhancement to execution tracing. Now when tracing is enabled, every time a message is sent, a session changes state, or a buffer is viewed or modified, a tracing event will be emitted. Downstream users can add a world Observer for the TracedEvent event to handle these events as they happen. If no observer is added, the overhead of tracing will be minimal, especially if message tracing (serializing the messages to record them) is turned off.

When tracing is turned off, it has virtually no overhead at all. If the "trace" feature is turned off at compilation time, then there will be no overhead at all from tracing, but it will also be impossible to enable tracing at runtime.

Migration Guide

Working on this feature took me on a long tour through the whole crossflow codebase, and gave me an opportunity to reevaluate the implementations of many modules. I saw some opportunities to improve other aspects of the library along the way. This PR introduces some API improvements, which for better or worse also mean API breakages.

Previously Replace With
In<BlockingService<T, S>> BlockingService<T, S>
BlockingServiceInput<T, S> BlockingService<T, S>
In<AsyncService<T, S>> AsyncService<T, S>
AsyncServiceInput<T, S> AsyncService<T, S>
In<ContinuousService<T, S>> ContinuousService<T, S>
ContinuousServiceInput<T, S> ContinuousService<T, S>
In<BlockingCallback<T, S>> Blocking<T, S>
BlockingCallbackInput<T, S> Blocking<T, S>
In<AsyncCallback<T, S>> Async<T, S>
AsyncCallbackInput<T, S> Async<T, S>
BlockingMap<T, S> Blocking<T, S>
AsyncMap<T, S> Async<T, S>
In<T> Blocking<T> or Async<T>
.into_blocking_service() No longer needed (use Blocking as function argument)
.into_async_service() No longer needed (use Async as function argument)
.into_blocking_callback() .into_callback() (use Blocking as function argument)
.into_async_callback() .into_callback() (use Async as function argument)
.as_map() .into_map()
.as_callback() .into_callback()

The overall theme is we've reduced all of the above input parameters into these:

Services Services, Callbacks, and Maps
BlockingService Blocking
AsyncService Async
ContinuousService

Blocking and Async can be used across services, callbacks, and maps. They are the same as BlockingService and AsyncService except they don't have a provider: Entity field because callbacks and maps are not associated with any Entity. Functions that don't care about having a provider can be used to implement a service or callback by using Blocking or Async. Functions that use Blocking or Async and have no other arguments can be used across all three types: services, callbacks, and maps.

Buffer access

To facilitate tracing, some API changes were made to BufferAccess and BufferAccessMut. For buffer tracing to be effective, we need to know what operation is accessing the buffer. The BufferKey alone doesn't tell us this since it can be freely passed around between operations and has no way of knowing which operation is using it.

Instead we add a new RequestId argument to BufferAccess::get(~) and BufferAccessMut::get_mut(~). Each request sent to each operation has a unique ID used for tracing. To obtain that ID, every operation argument has a new id: RequestId field. Simply pass that id field along to get(id, &key) or get_mut(id, &key) so that the access can be traced.

Note that BufferAccess::get now requires a mutable borrow of BufferAccess even though its buffer operations are read-only. This is because the tracing does require some mutability. This does not affect the ability of systems that use BufferAccess to be run in parallel.

If you want to use BufferAccess in a pure read-only, you can choose to use BufferAccess::get_untraced(&key), but as the name implies there will be no ability to track that access.

Additional issues fixed by this PR:

mxgrey and others added 30 commits February 17, 2026 06:12
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
mxgrey added 2 commits March 5, 2026 00:15
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
@mxgrey mxgrey added this to PMC Board Mar 4, 2026
@github-project-automation github-project-automation bot moved this to Inbox in PMC Board Mar 4, 2026
mxgrey and others added 8 commits March 5, 2026 00:28
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
Signed-off-by: Michael X. Grey <mxgrey@intrinsic.ai>
@mxgrey mxgrey marked this pull request as ready for review March 5, 2026 06:17
mxgrey added 6 commits March 5, 2026 17:25
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Signed-off-by: Michael X. Grey <greyxmike@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant