Crate tcslog_tools 

The crate’s documentation is its README, included below.

These are two command-line programs, so this library target exists only to carry that documentation: it exports nothing and no dependent has reason to link it. Without it the crate has no library to document, and docs.rs has no page for the crate at all – only one per binary, which is not where anyone looks first.

The README is included rather than copied so that the two cannot drift. It is what crates.io renders as well, so one text serves both.

tcslog-tools

Command-line tools for inspecting tcslog segment files.

tcslog-dump walks a whole log — a directory of segment files sharing a prefix and suffix — and prints the records it recovers, with the losses it found. tcslog-dumphdr prints one segment file’s header, reading the bytes it is handed and never the file’s name, so it also serves a file that has been renamed or copied out of its log.

Both tools only read. They take tcslog with its default write feature turned off, so neither needs the TIMER_RESOLUTION the writing side requires at build time.

Installing

cargo install tcslog-tools

Or from a checkout, into $HOME/bin:

make install

make install PREFIX=/usr/local chooses somewhere else and DESTDIR stages the install for packaging. make uninstall removes both binaries again, honouring the same two variables.

tcslog-dump

tcslog-dump <dir> <prefix> <suffix> [--verbose] [--text]

Without options it prints one line per record and nothing else, which is what to pipe into something else. A payload prints as hexadecimal: two lower-case digits a byte, one space between, which assumes nothing about telemetry that is mostly not text.

• -v, --verbose — also print a block for every segment file the read passed through, a notice wherever telemetry was lost or a record did not fit, a marker at each session boundary, and totals at the end.
• -t, --text — display payloads as ASCII. A printable character prints as itself; everything else prints as an escape — \n, \r, \t, \\, or \xNN — so that no byte of telemetry can move the cursor, start an escape sequence that swallows what follows, or break one record across two lines. The escape also says which byte was there. Without the flag a payload prints as hexadecimal.
• -h, --help — print the options to standard output and exit 0, so the help can be piped. --version does the same. A usage error puts both the complaint and the help on standard error and exits 2, leaving standard output carrying nothing but what was asked for.

tcslog-dumphdr

tcslog-dumphdr <file>
tcslog-dumphdr < <file>

Prints the header on a single line. It reads the file named on the command line, or standard input when none is named. It reads only the header, so the standard input form works on a pipe whose writer is still running. A read failure exits 1 and a usage error exits 2.

Building from a checkout

The tcslog dependency is a path to a sibling checkout, so clone both repositories side by side:

git clone https://github.com/vomlehn/tcslog.git
git clone https://github.com/vomlehn/tcslog-tools.git
cd tcslog-tools && cargo build

cargo publish substitutes the registry version for that path, so a release does not depend on the layout.

Documentation

The manual is docs/tcslog-tools.rst in the repository, which covers both tools at greater length than this page; make -C docs renders it to docs/tcslog-tools.html.

The log format these tools read, the record formats, and the recovery rules they report on belong to the library and are described in docs/tcslog.rst in the tcslog repository.

License

Dual licensed under MIT OR Apache-2.0.