Trace Files

Nanoconda API supports recording all API requests and session callbacks into a trace file.

Trace files can later be replayed to reproduce a trading session for debugging, testing, strategy validation, deterministic simulation, and production issue analysis.

Generating a Trace File

To start recording a trace file, provide the desired trace file name to nanoconda::start().

nanoconda::start("myTraceFile.naco");

Market data tracing can also be enabled, and the trace writer thread can optionally be pinned to a dedicated CPU core.

Full function signature:

void start(const char* tracefile = "", bool traceMarketData = false, int traceCpu = -1);

Parameters

Parameter	Description
`tracefile`	Path and name of the trace file to generate
`traceMarketData`	Enables recording of market data callbacks in addition to API requests and session callbacks
`traceCpu`	Optional CPU core affinity for the trace writer thread. `-1` disables CPU pinning

Notes

Trace recording begins immediately after session startup.
Trace files preserve callback ordering and API request sequencing.
Market data tracing may significantly increase trace file size and disk bandwidth usage.

Replaying a Trace File

To replay a previously recorded trace file, call nanoconda::replayTrace() instead of nanoconda::start().

nanoconda::replayTrace("myTraceFile.naco");

During replay:

No live exchange connectivity is required
No orders are transmitted to the exchange
Recorded callbacks are replayed in their original order
API requests captured in the trace are reproduced deterministically

This allows strategies and plugins to be tested offline against previously recorded trading sessions.

Trace Replay Callbacks

Trace replay produces several additional callbacks beyond the standard live session callbacks. These callbacks allow applications to observe when recorded API requests occurred during replay.

Trace Replay Dedicated Callbacks

virtual void onneworder(const order* order) { }
virtual void onmodifyorder(const order* order) { }
virtual void oncancelorder(const order* order) { }
virtual void oncancelall() { }
virtual void ontracecomplete() { }
virtual void onriskerror(const error* error) { }

Callback Description

Callback	Description
`onneworder()`	Triggered when a recorded new order request is replayed
`onmodifyorder()`	Triggered when a recorded modify request is replayed
`oncancelorder()`	Triggered when a recorded cancel request is replayed
`oncancelall()`	Triggered when a recorded cancel-all request is replayed
`ontracecomplete()`	Called when replay reaches the end of the trace file
`onriskerror()`	Triggered when a recorded pre-trade risk rejection occurs

Trace Replay Utility

Nanoconda CLI includes a dedicated replay application named traceplayer for convenient replay of trace files through a plugin.

traceplayer          Replay a Nanoconda trace file using a plugin

Example:
nanoconda-cli -a traceplayer -i plugin.so -f myTraceFile.naco

Example

nanoconda-cli -a traceplayer -i mystrategy.so -f session.naco

This launches the replay engine and forwards replayed callbacks into the specified plugin.

Common Use Cases

Trace files are commonly used for:

Strategy debugging
Regression testing
Production incident analysis
Order flow analysis

Notes

Replay preserves the original callback ordering captured during recording, with the exception of onriskerror(), which may be recorded with a slight delay to allow burst risk errors to be conflated into a single event.
Applications should handle ontracecomplete() to detect end-of-replay conditions.
Replay callbacks use the same callback interface as live sessions wherever possible.
Trace files are intended for offline simulation, testing, and debugging workflows.