Upstreaming Runtime Monitoring and Tracing #1406

steve-the-edwards · 2025-08-01T16:15:12Z

This is the evolution of a class we've long used in production internally. This takes a lot of the bookkeeping that we had there and makes it available to other pluggable WorkflowRuntimeTracers.

There is also an update to the RuntimeUpdate type that is clearer about when the runtime loop is finished (regardless of if the rendering is skipped or not).

First commit removes the old TracingWorkflowInterceptor and the corresponding trace-encoder module.

The second commit adds the WorkflowRuntimeMonitor as well as a bunch of reflection-less logging utilities that we've used for some time.

rjrjr · 2025-08-01T16:24:08Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/Loggable.kt

+ * to customize their logging names for [WorkflowRuntimeMonitor] output.
+ */
+public interface Loggable {
+  public fun toLogString(): String = toString().wfStripSquarePackage()


When thinking about upstreaming this I always felt bad about how com.squareup.com is hard coded into wfStripSquarePackage(). Wonder if we should expose a static property or something to allow customization. I don't think that should derail this initial commit, just food for thought.

But in the meantime, it does seem sketchy to have a default implementation that relies on a non-public function.

Is this call redundant here anyway? Do we also make downstream calls?

we can remove the default.

Wise, it's a terrible default anyway. Shouldn't be making it so easy to use toString() by accident, defeats the purpose.

Wonder if we should expose a static property or something to allow customization. I don't think that should derail this initial commit, just food for thought.

I thought about this too, but its a bit confusing to add and is a lot of power to munge the logs that i landed on just keeping it simple.

rjrjr · 2025-08-01T16:25:34Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/RuntimeLoggingUtils.kt

+  /**
+   * Used as a key to detect actions originating from the Workflow that implements a worker.
+   */
+  // Keep this up-to-date with the action in com.squareup.workflow1.WorkerWorkflow.


Do we have a unit test that will break if we screw that up?

No. but we should. I will add.

Did one better and just made it a constant in Worker.kt shared in both places

rjrjr · 2025-08-01T16:28:43Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/RuntimeLoggingUtils.kt

+/**
+ * Alternative to [toString] used by Workflow logging.
+ */
+internal fun getWfLogString(log: Any?): String {


Making this function non-public defeats a major use case. We want feature code implementing Loggable to be able to call this on members so that the opt-in scheme works recursively. I'd be inclined to most or all of this file public -- making Loggable public without this invites serious footguns.

I can make it public, but my general idea was that you would implement your own getLogString() to handle more cases than what we can include here.

Better to err on the side of privacy probably. Easier to open up later.

the getLogString implementation is less broad than ours in register, because there are a lot of internal types that we don't want to lift here that we handle.

My idea was that we could keep using our Loggable as SquareLoggable for those, if desired.

That's a good idea. If it feels good once you've tried it out could suggest it in the kdoc here.

I wonder how many of our internal types we could get out of the big if / else if they implemented Unwrappable?

rjrjr · 2025-08-01T16:29:34Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/RuntimeUpdateLogLine.kt

+import com.squareup.workflow1.tracing.ActionAppliedLogLine.WorkflowActionLogType.WORKER_OUTPUT
+
+/**
+ * PLEASE NOTE: these logs lines are turned into strings in production, all the time, and there


"log lines"

rjrjr · 2025-08-01T16:46:05Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/RuntimeTraceContext.kt

+  public var currentRenderCause: RenderCause?
+
+  /**
+   * Add an update into the [RuntimeUpdates] tracked by [WorkflowRuntimeMonitor].


The kdoc on RuntimeUpdateLogLine is more informative, should probably say a lot of that here instead / too.

We can suggest a useful spot to call this from (see below).

Be good to update the kdoc of reportNavigation to draw attention to this, or if dependencies allow it add this to the default onNavigate param value.

* Consider calling this from the `onNavigate` function you provide to * `reportNavigation`, e.g. * * val renderings: Flow<Screen> by lazy { * renderWorkflowIn( * workflow = RootNavigationWorkflow, * scope = viewModelScope, * savedStateHandle = savedState, * runtimeConfig = RuntimeConfigOptions.ALL * ).reportNavigation { * runtimeMonitor.addRuntimeUpdate( * UiUpdateLogLine(getWfLogString(it)) * ) * }

btw, TIL about NavigationMonitor!

Yeah, I snuck that out when updating the tutorials. I'm proud to report that we use it in prod, it's solid.

rjrjr · 2025-08-01T16:51:44Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/WorkflowRuntimeTracer.kt

+  /** SECTION: [WorkflowInterceptor] overrides. */
+
+  /**
+   * [WorkflowRuntimeTracer]s should not override this method, using [onWorkflowSessionStarted]


It can't b/c this is final, so "should not" is an odd thing to say.

I guess i was just diary-ing my thoughts rather than making clear kdoc. Will change.

rjrjr · 2025-08-01T16:53:47Z

workflow-tracing/build.gradle.kts

+  api(libs.androidx.collection)
  api(libs.kotlin.jdk8)
  api(libs.kotlinx.coroutines.core)
+  api(libs.squareup.papa)


Is this direct tie to papa going to cause dependency hell down the road? Can we introduce a separate module that ties to papa, similar to what we did for radiography?

sure, we could

Done. separate out into workflow-tracing-papa

Upstream from our internal project; including with papa tracing. Adds a bunch of tests for verification of behaviour.

mannydelgado · 2025-08-04T14:55:42Z

workflow-tracing-papa/src/main/java/com/squareup/workflow1/tracing/papa/WorkflowPapaTracer.kt

+ * By default this uses [PapaSafeTrace] which will use [androidx.tracing.Trace] calls that
+ * will be received by the system and included in Perfetto traces.
+ */
+class WorkflowPapaTracer(


This has the potential to be more of a generalized Tracer, where anything that has extended SafeTraceInterface can work here.

SafeTraceInterface has the workings of what could be a generalized approach with its current functions.
Might need renaming but that could be done in the future.

ya, we can iterate. not many users (only us) of this for now.

zach-klippenstein · 2025-08-12T00:16:48Z

workflow-runtime/src/commonMain/kotlin/com/squareup/workflow1/WorkflowInterceptor.kt

+   * The runtime has finished its work and is stable again - either skipping rendering because
+   * of no change ([RenderPassSkipped]), or having passed a new rendering ([RenderingProduced]).
+   */
+  public data object RuntimeLoopTick : RuntimeUpdate


Nit: The name could be more descriptive, maybe RuntimeSettled?

zach-klippenstein · 2025-08-12T00:18:57Z

workflow-tracing/src/main/java/com/squareup/workflow1/tracing/ConfigSnapshot.kt

+  val csrConfig = config.contains(CONFLATE_STALE_RENDERINGS)
+  val ptrConfig = config.contains(PARTIAL_TREE_RENDERING)
+  val deaConfig = config.contains(DRAIN_EXCLUSIVE_ACTIONS)
+  val sehConfig = config.contains(STABLE_EVENT_HANDLERS)
+  val wsdConfig = config.contains(WORK_STEALING_DISPATCHER)


These properties are public API, they should probably not use abbreviations.

Remove trace-encoder and old TracingWorkflowInterceptor

610b92a

rjrjr reviewed Aug 1, 2025

View reviewed changes

steve-the-edwards force-pushed the sedwards/runtime-tracing branch from 7b71c90 to 40ad34f Compare August 1, 2025 19:55

Upstream WorkflowRuntimeMonitor; Change RuntimeUpdates API

629bbe5

Upstream from our internal project; including with papa tracing. Adds a bunch of tests for verification of behaviour.

steve-the-edwards force-pushed the sedwards/runtime-tracing branch from 40ad34f to 629bbe5 Compare August 1, 2025 20:18

steve-the-edwards marked this pull request as ready for review August 1, 2025 20:21

steve-the-edwards requested review from a team and zach-klippenstein as code owners August 1, 2025 20:21

steve-the-edwards requested a review from rjrjr August 1, 2025 20:21

steve-the-edwards enabled auto-merge August 1, 2025 20:44

mannydelgado reviewed Aug 5, 2025

View reviewed changes

mannydelgado approved these changes Aug 11, 2025

View reviewed changes

steve-the-edwards requested a review from mannydelgado August 11, 2025 15:50

zach-klippenstein approved these changes Aug 12, 2025

View reviewed changes

steve-the-edwards merged commit d60b6e5 into main Aug 12, 2025
69 checks passed

steve-the-edwards deleted the sedwards/runtime-tracing branch August 12, 2025 00:20

steve-the-edwards mentioned this pull request Aug 12, 2025

Follow-up cleanups from Runtime Tracing Upstream #1407

Merged

Upstreaming Runtime Monitoring and Tracing #1406

Upstreaming Runtime Monitoring and Tracing #1406

Uh oh!

Conversation

steve-the-edwards commented Aug 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rjrjr Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rjrjr Aug 1, 2025 •

edited

Loading