Skip to content

Write logs from your modules

Documented releasev0.2.0/Stable main branch

Continue from Your first RPC. This time, record what the sender and receiver are doing, using four log levels:

Level When to use it In this example
Debug Details useful while debugging Preparing a message
Info Normal activity Starting a module or receiving a message
Warn A problem the module can continue past An unknown command
Error An operation failed An RPC request failed

The example uses logPublisher and logSubscriber. They keep the instance names sender and receiver, with the same message and RPC commands as before.

Use context.log.write(level, text) inside a module. Both modules put this call in a small named helper:

logging/publisher.cpp
void write_log(vinc::log::Level level, std::string_view text) {
// Write one log entry; report rejected logs without stopping the module.
auto logged = context.log.write(level, text);
if (!logged) {
std::cerr << "Log rejected: " << vinc::error_to_string(logged.error()) << std::endl;
}
}

logging/publisher.cpp · e165aed

The helper reports a rejected log through ordinary output, so a logging failure does not interrupt message handling.

For example, the receiver writes an Info entry when a message arrives:

logging/subscriber.cpp
void on_message(std::unique_ptr<vinc::CounterSample> message) {
// Subscription callback: called when a counter message is delivered.
++received_;
write_log(vinc::log::Level::Info,
"counter received sequence=" + std::to_string(message->data().sequence.get()));
std::cout << "received sequence=" << message->data().sequence.get()
<< " publisher=" << message->publisher_name() << std::endl;
}

logging/subscriber.cpp · e165aed

The existing console output remains, so you can still see the result of a command when log display is off.

From the open-vinc-examples repository root, rebuild the project prepared in the earlier lessons. Close any previous Vinc Shell with exit before launching again.

Terminal window
cmake --build build/debug
.\build\debug\Vinc.exe

Once you see VINC ready, enter in Vinc Shell:

log show on

Log display is off by default. This command turns it on for the current Shell. Its default level is Info, which shows Info, Warn, and Error.

Start the receiver:

logSubscriber

Wait for Started receiver, then start the sender:

logPublisher

Wait for Started sender. You will also see log entries containing level=INFO and receiver started or sender started. Each entry includes its module name and time.

Now send a message:

sender send

Wait for received sequence=1 publisher=sender. The receiver also records an Info log containing counter received sequence=1.

Enter sender count; the sender records RPC count=1 and prints the familiar RPC received=1.

By default, modules skip Debug logs. To see the sender’s details, change both its source level and the Shell display level:

log level sender debug
log show debug
sender trace

sender trace is a command in this example that writes a Debug entry. Wait for trace debug_enabled=1 and a log containing level=DEBUG and trace detail.

The source update is asynchronous. If you see trace debug_enabled=0, enter sender trace again after a moment.

These two settings control different things:

Command What it changes
log level sender debug The levels the sender produces
log show debug The levels this Shell displays

Changing only log show debug cannot show Debug entries that the module skipped. Debug includes all four levels; Info excludes Debug; Warn keeps Warn and Error; Error keeps only Error.

Keep the sender’s source level at Debug and narrow the Shell display:

log show warn
sender invalid

You will see a Warn log containing unknown sender command, along with the command usage.

Next, deliberately ask a module that does not exist:

sender count missingReceiver

You will see an Error log containing RPC request failed:. An Error entry records the failure; it does not stop the module. Enter sender count again to confirm that the real receiver still replies with RPC received=1.

Info and Debug logs are hidden by the Shell filter. Ordinary command output, such as RPC received=1, remains visible.

To hide logs in this Shell:

log show off

This only turns off display. It does not stop log collection or file output. Finish with:

exit

Wait for the modules to stop and return to PowerShell.

Where are the log files?

By default, Vinc writes logs under <executable directory>/vinc_data/<VINC_NAME>/logs/, grouped by date. For this example:

  • C++: build/debug/vinc_data/counter-example/logs/
  • Python: build/python/vinc_data/python-tutorials/logs/

Use log status in Vinc Shell to check file output status. Display filtering does not remove entries from the files; source filtering skips entries before they are collected.