runtime_tracing

A format and helper library for CodeTracer traces

format

A CodeTracer trace for its db backend consists of record data, metadata for the recorded program and copy of the relevant source/repository files. It's self contained, so one can debug a record of a version of a program from a different commit or branch. The record data consists of a stream of objects, each of which describes a certain program event: call, step, return etc.

A trace contains several files:

• trace.json – the event data in JSON format
• trace.bin – the same event stream encoded in a binary format (see docs/trace_binary_spec.md)
• trace_metadata.json – metadata for the recorded program
• trace_paths.json – a list of the recorded files
• files/ – a folder including all the source/repository files copied into the trace.

The event stream can be stored either as JSON (trace.json) or in the binary format (trace.bin). Both representations correspond to the Rust types in src/types.rs.

We plan on

• defining a more precise document or a list of examples or a specification.
• producing a more optimized version of the format. A binary variant is now available as trace.bin.

A future goal of this format is to make it possible to stream traces: to be able to replay them while they're still being recorded. This is one of the reasons for the decision to maintain a single "stream" of events currently.

tracer library

We also define a Rust tracer library in src/tracer.rs which can be used as a helper to instrument Rust-based language interpreters and vm-s. It can make it easier to migrate to newer versions of the format, hiding many details behind its helpers. There are a few examples and tests of its usage in src/lib.rs.

There are some actual usages of it as well which can be also used as an example:

• in blocksense-network/noir: their tracing support for CodeTracer
• in a small toy interpreter to be released as a part of the CodeTracer repo

One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases!

Building the Documentation

The library API docs can be built locally with:

cargo doc --all-features --no-deps

The generated HTML documentation will be placed under target/doc. Open target/doc/runtime_tracing/index.html in a browser to inspect it.

Publishing to crates.io

After updating the version number in Cargo.toml, publish a new release with:

cargo publish

Documentation for released versions will be automatically hosted on docs.rs.

Legal

Authored and maintained by Metacraft Labs, Ltd

LICENSE: MIT