Software Diagnostics Library

Semantic Mapping is the trace and log analysis pattern where opaque runtime identifiers such as PIDs, TIDs, request IDs, handles, or session IDs are renamed or mapped to semantically meaningful diagnostic entities such as UI Thread, Worker Thread, Client Process, Blocking Thread, or Failed Request:

Additionally, in Semantic Mapping, we cannot only rename identifier values but also rename the Trace Schema itself, for example, changing column headers such as PID to Process and TID to Thread.

This analysis pattern differs from Trace Field, which is a mapping/function from trace messages to some other domain. It does not necessarily rewrite the trace presentation itself, but it may add additional ATID c to the Trace Schema. It is also different from Semantic Field, which is a semantic category/codomain/class into which trace messages are grouped, which is more about the meaningful domain of classification, not about rewriting trace labels. On the contrary, Semantic Mapping is a representation transformation that rewrites the trace into a more meaningful diagnostic form. It operates at two levels: instance level, renaming actual values, and schema level, renaming the fields/headers themselves.

Here is another example adapted to agentic AI:

Using mathematical analogies, Semantic Mapping is essentially a readability-preserving isomorphism: the structural information is unchanged, but a human (or AI analyst) now works in a named, meaningful coordinate system rather than an anonymous numeric one.

- Dmitry Vostokov @ DumpAnalysis.org + TraceAnalysis.org -

Usually, in traces and logs, messages from different components are highly interleaved. Direct chronological reading may cause confusion because every component’s Adjoint Thread of Activity appears entangled with every other one:

Bethe Ansatz analyzes such a trace by treating requests, threads, agents, transactions, or log-producing entities as “quasi-particles” whose global behavior can be reconstructed from many local pairwise interactions. The inspiration for the pattern name comes from Bethe ansatz, introduced by Hans Bethe in 1931. In physics, it is a method for constructing exact solutions of certain many-body systems: in integrable systems, complex many-body scattering can be represented through factorized two-body scattering processes. In trace analysis, we often face a “many-body” problem: many requests, threads, services, queues, locks, agents, retries, callbacks, and timeouts interact within a single shared diagnostic space. Instead of trying to understand the whole trace as one monolithic event cloud, we decompose it into stable activity lines and pairwise encounters that may explain the global behavior:

The Bethe ansatz has many forms, including coordinate, algebraic, analytic, functional, nested, and thermodynamic variants. For this pattern, the most useful metaphor is the coordinate Bethe ansatz: represent the global state by positions of entities and interaction effects between them. We have the following analogies:

• Particle/excitation: request, thread, transaction, agent, session, workflow
• Coordinate: timestamp, component, hop number, queue position, memory address, trace span
• Momentum/rapidity: (activity) rate, latency class, retry rhythm, priority, causal direction
• Two-body scattering: (pairwise interaction) lock contention, queue wait, API call, resource conflict
• Scattering phase shift: delay, reordered event, changed state, timeout extension, retry offset
• Factorized many-body scattering: whole trace explained as composition of pairwise effects
• Bethe equations: consistency constraints imposed by loops, boundaries, cycles, repeated paths
• Non-integrability: residual behavior not explainable by pairwise interactions

Interactions can be found among Motifs, Macrofunctions, and actors of Activity Theatre.

We suggest the following diagnostic analysis procedure:

1. Identify trace quasi-particles that preserve identity across the trace.
2. Choose a coordinate system: the trace can be read through coordinates other than time.
3. Detect pairwise encounters: look for places where two entities interact; these are diagnostic “scattering” events.
4. Estimate phase shifts where a pairwise encounter often changes the apparent trajectory of an activity. The phase shift is the observable deformation caused by interaction.
5. Test factorization by asking the question: Can the global anomaly be explained as a product of pairwise interactions?

If the answer to the last question is yes, then the system is “Bethe-like”: complex but decomposable. If the answer is no, there may be a true many-body effect, such as shared cache collapse, global scheduler starvation, cascading timeout storm, distributed deadlock, correlated retry amplification, emergent agentic loop, or resource exhaustion caused by collective behavior.

Additionally, we can form a Motivic Trace from the resulting pairwise interaction layers. Motivic Trace compresses a trace into explanatory motives. Bethe Ansatz compresses a trace into pairwise interaction motives whose composition reconstructs the observed global behavior. In this sense, Bethe Ansatz can be viewed as a structured route to Motivic Trace: first decompose the tangled chronological trace into stable activity lines and pairwise encounters; then integrate those encounters into higher-level explanatory motives such as queue delay, database lock wait, retry ordering, and response ordering. In summary: Motivic Trace is the broader compression pattern; Bethe Ansatz is a pairwise-factorized way to build it.

A historical note: this analysis pattern also extends physical analogies of debugging.

- Dmitry Vostokov @ DumpAnalysis.org + TraceAnalysis.org -

Usually, software traces and logs are sorted by time.

Spatial Form is a specialized Sorted Trace in which trace or log messages are sorted by spatial, topological, or diagnostic proximity to a chosen origin component, device, process, service, or subsystem. Instead of reading the trace solely as a chronological sequence, we choose a diagnostic origin and arrange messages by their distance from that origin. Within each distance layer, the original local time order may still be preserved.

The pattern name comes from Joseph Frank’s The Idea of Spatial Form that is associated with reading narrative structure through juxtaposition and relational arrangement rather than only through linear chronological progression; the concept was introduced into literary discussion through his 1945 essay and later collected with reconsiderations in his book.

Sorted Trace is the more general pattern: messages are sorted according to some attribute value, for example, by TID, ATID, message type, message invariants, or message data.

For Spatial Trace, the distance may come from network topology, service dependency graph, component containment, process/thread ownership, device hierarchy, pipeline stage distance, proxy/gateway chain, address-space relation, storage or shard topology, causal adjacency, and many others. The resulting trace is not anti-temporal. It is spatially primary and temporally secondary.

Spatial Trace analysis pattern may help answer these questions: What happened around this proxy? Which nearby component first showed abnormal behavior? How did the request propagate outward? Was the fault local, adjacent, or remote? It may help distinguish local symptoms, adjacent symptoms, downstream effects, remote dependencies, and external causes. It gives the trace a layered diagnostic structure and spatial Layered Periodization. The pattern is therefore both a sorting technique and a reading strategy.

This pattern is especially useful for distributed systems, microservices, network devices, storage stacks, cloud control planes, request pipelines, proxies, gateways, and agentic AI workflows where activity is spread across many components.

- Dmitry Vostokov @ DumpAnalysis.org + TraceAnalysis.org -