simpletrace

An incredibly simple c++ tracing library.

If you found this you probably want something like binlog and not this project.

This is more of a simple library to help with my own tracing needs within personal projects. My goals were

1. extremely lightweight binary logging that could multipurpose as tracing
2. a very simple schema that could allow logs to be extracted to sqlite, tabular format, etc
3. tiny overhead if runtime disabled, and compile-time-disable for zero overhead.

The idea being that basic tracing is supported, but that we could add arbitrary data on an ad-hoc basis that could be immediately understood by consumers (trace sinks & writers).

Quick start

Basic scoped trace

#include "scoped_trace.h"
#include "ndjson_trace_writer.h"

int main() {
  using namespace simpletrace;
  ndjson_trace_writer_t writer{"trace.json", 1 << 20};
    impl::set_tls_writer(&writer);
    {
      SIMPLETRACE_SCOPED_TRACE("doing work");
      // ... your code ...
    }
    writer.flush();
}

This writes a beginning and end scope_trace_event_t for the labeled block. The label must be a string literal (or other static storage string) so no string data is copied.

If the output file cannot be opened or the stream is otherwise invalid during construction, ndjson_trace_writer_t throws a std::runtime_error.

Custom events

Define a struct with the provided macros to describe the fields of the event.

#define MY_EVENT_FIELDS(X) \
  X(int32_t, answer) \
  X(std::string_view, message)
SIMPLETRACE_EVENT_STRUCT(my_event_t, MY_EVENT_FIELDS);

Emitting the event is then just:

my_event_t e{.answer = 42, .message = "hello"};
writer.write_type(e);

The macro registers the type with trace_registry_t, so readers know how to decode the bytes.