trice

README

Trice - Trace IDs for Embedded C/C++

🅃🅁ace 🄸d's for 🄲 🄴mbedded

View GitHub Pages

Hi, I am Trice.

---

Trice is an ultra-low-overhead logging framework for embedded C/C++. It provides printf-like usability with only ~6–100 CPU cycles per log call, making logging practical even when used from interrupt handlers in real-time firmware systems.

Log in a trice — with Trice, even from ↯ interrupt handlers in less than 1 µs ❗

Trice User Manual: GitHub • GH Pages • PDF

Overview (click to expand)

• What is Trice?
  • Key Benefits
  • How it works
  • Result
  • Two Parts of Trice
• Quickstart: First RTT Log with J-Link
• When to Use Trice
  • Logging and Debugging
  • Data Compression
  • FLASH Memory Storage
  • Encryption
  • Translation
  • Timing Analysis
• How Trice Works (UART Example)
• Data Transfer Options
  • Implemented Transfer Methods
  • Other Transfer Options
• Display Server
• Documentation
• Debugging with VS Code and Clang
• Trice Cache
  • When to Use Cache
  • How Cache Works
  • Important Note
• Which Mode Should You Use?
• Project Status
• Future Plans
• Support the Project
• Similar Projects

What is Trice?

Trice is designed for systems where traditional logging is too slow, too large, or not safe to use in interrupt or real-time contexts.

Trice replaces printf-style logging in embedded C/C++ systems with a much faster and more efficient approach.

Instead of formatting and storing strings on the target, Trice encodes log messages as compact IDs and keeps the actual strings on the host. This reduces runtime overhead, memory usage, and data transfer size.

Key Benefits

• 🚀 Speed – ~6–100 CPU cycles per log call. This makes logging practical even when used from interrupt handlers in real-time firmware systems.
• 📦 Small Size – no format strings stored in target FLASH
• 🧱 Version Stability – decode logs from older firmware without requiring matching tool versions
• 🛠 Easy Migration – reuse existing printf-style code with minimal changes via the -alias option
• ➕ More Features – flexible logging, transport options, and tooling

How it works

1. Use Trice macros instead of printf in your firmware (or use the trice i -alias option).
2. At build time, Trice assigns each log message a compact ID while the user source code stays unchanged.
3. The target device sends only IDs and data.
4. The host reconstructs the original messages using the Trice ID list.

- printf("Temperature: %d°C", t);
+ trice("Temperature: %d°C", t);   // fast, compact, ID-based

Result

• Faster execution
• Smaller binaries
• Reliable logging in time-critical code paths

Two Parts of Trice

1. C code macros - Provide a familiar printf-like interface at the application level, but internally send just ID and values instead of full format strings. The Trice tool maps these IDs back to readable text.
2. Trice tool - Manages and displays the logs
   • Written in Go - works on all platforms that Go supports
   • You can also build your own tool to receive Trice packages, replace IDs with text, and display the output

Ready to use: Start with Trice

Quickstart: First RTT Log with J-Link

Install the trice tool. Use a latest release binary and put it into your PATH.

For a first setup, SEGGER RTT is usually fastest: it needs no MCU-specific UART driver and works via J-Link. Install the SEGGER J-Link software package so JLinkRTTLogger is in PATH.

1. Add the complete src folder to your target project unchanged and add ./src to the compiler include path.
2. Create a project-specific triceConfig.h file with this minimal direct RTT configuration:

#define TRICE_DIRECT_OUTPUT 1
#define TRICE_BUFFER TRICE_STACK_BUFFER
#define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1

1. Add Trice to your code, for example in main.c:

#include "trice.h"

int main(void) {
    TriceInit(); // RTT-specific
    // ... system init
    trice("Hello world!\n");
    // ...
}

1. Create empty til.json and li.json files in your project root and run trice insert -src ./ before compiling. This assigns IDs to your trice(...) calls and fills both JSON files.
2. Build and flash your target.
3. Start logging with your device name (add -v for details)

trice log -p JLINK -args "-Device STM32G0B1RE -if SWD -Speed 4000 -RTTChannel 0" -pf none -prefix off -hs off -d16 -i ./til.json -li ./li.json

Or use the file-based RTT logger workflow manually:

Terminal 1 (remove any old log file and create the file):

rm -f ./temp/trice.bin
touch ./temp/trice.bin
JLinkRTTLogger -Device STM32G0B1RE -If SWD -Speed 4000 -RTTChannel 0 ./temp/trice.bin

Terminal 2:

trice log -p FILE -args ./temp/trice.bin -pf none -prefix off -hs off -d16 -ts ms -i ./til.json -li ./li.json

For more setup details, see Start with Trice, Configuration file triceConfig.h, and Trice over RTT.

When to Use Trice

Logging and Debugging

You can use Trice for printf debugging and as a logging system. The advantage is very short messages (no strings) for data transfer. Keep your project-specific til.json file available to decode field logs later. The repository example file is demoTIL.json.

• Optional: Add your project-specific til.json as a compressed resource to your target image. You can use SRecord or provide a download link.

Data Compression

Replacing format strings with IDs at compile time acts like strong data compression for FLASH and transferred log data, while making target-side logging orders of magnitude faster at runtime.

FLASH Memory Storage

Store Trice messages in FLASH memory for later analysis. A typical trice uses only 4 bytes, no matter how long the format string is.

Encryption

You can encrypt Trice transfer packets for security.

• Deliver firmware images with encrypted Trice output that only works with the right key and the matching til.json
• XTEA encryption is available

Translation

Translate the til.json file into different languages. Change the language by changing the til.json file without changing the target binary.

Timing Analysis

Trice makes timing analysis easy on distributed embedded systems. It supports both host and target timestamps.

How Trice Works (UART Example)

This simplified diagram shows how Trice works. Read the detailed explanation here.

Data Transfer Options

Implemented Transfer Methods

• UART - Can connect to virtual UART over USB
• RTT - Works with J-Link and ST-Link
• TCP4 (TCP4 input and TCP4 output)
• UDP4 (UDP4 input)

Other Transfer Options

• Use a small separate microcontroller as a bridge from GPIO, I²C, SPI, CAN, LIN to UART
• Use FTDI chips like Adafruit FT232H Breakout for easy GPIO, I2C, and SPI access

Display Server

• Start trice ds in a console on your local PC or a remote PC. Then connect several trice tool instances using commands like trice log -p COM15 -ds
• This allows you to see the Trice logs of several devices line-by-line intermixed in one terminal.

Documentation

The Trice User Manual includes all information from the Memfault Interrupt Blog which is slightly outdated.

• Check issues and discussions, including closed items
• Read the target source code, especially triceDefaultConfig.h
• View CLI options by running trice help -all in a terminal or reading the generated file trice-help-all.txt
• Refresh the checked-in CLI help documentation with go generate ./internal/args
• Look at and modify ./internal/emitter/lineTransformerANSI.go if needed (requires running go install ./cmd/trice/... afterwards)

Debugging with VS Code and Clang

Debug a Trice project in Direct-Out Mode over SEGGER-RTT. (See Development Environment Setup for details.)

Trice Cache

(click to expand)

---

You can use the -cache CLI switch with trice insert and trice clean commands. This only works when you create the .trice/cache folder in your home directory. (Trice Cache Details)

When to Use Cache

Use cache when you:

• Use trice i ... before compiling
• Use trice c ... after compiling
• Want to keep IDs out of your source code when working
• Want faster compilation

How Cache Works

The Trice cache saves copies of all files after processing them with trice i or trice c. This avoids inserting and removing IDs repeatedly. The copies are used to get the same results for files that have not been edited. Edited files are processed normally and the cache updates afterwards. File modification times do not change, so the build system does not reprocess unchanged files even when IDs are temporarily removed.

Important Note

-> Be careful when your build system also modifies source files!

For example, run an auto-formatter before the trice insert command.

---

Which Mode Should You Use?

• For development: Direct mode with SEGGER_RTT is recommended
• For most use cases: Deferred mode with TRICE_BUFFER == TRICE_RING_BUFFER (uses less RAM) in TRICE_MULTI_PACK_MODE (transfers less data)

Project Status

Trice is fully usable.

+ Use the latest release or main branch to build from source.
- Do not use the "dev" branch. It may not work properly.

Future Plans

• The documentation could better explain advanced use cases, such as deferred remote procedure calls.
• A separate tlog tool written in C or Python would allow logging on any platform, not just platforms supported by Go.
• A draft specification for structured logging in Trice is available, based on feedback from #531.
• Proposals and feedback on these topics are welcome.

Support the Project

• Trice takes a lot of my free time. I want to keep it MIT licensed in the future.
• If you make profit using Trice in your products, donations help convince my family to continue improving Trice.
• ⭐ Star this project! ☺
• Support options:
  • Become a Sponsor with your GitHub account
  • 
  • 

Similar Projects

(click to expand)

---

• ARM ITM/SWO (hardware-native)
• ARM Keil Event Recorder (hardware-native)
• baical.net (C)
• call stack logger function instrumentation (trace program execution flow)
• Debugging with Dynamic Printf Breakpoints (Eclipse IDE option)
• defmt (Rust)
• Diagnostic Log and Trace (AUTOSAR)
• Embedded Logger (elog) (Embedded logger with minimal footprint and memory usage)
• Logging with symbols - The Embedonomicon
• McuLog (McuOnEclipse)
• MCUViewer
• Memfault Compact Log Library (part of firmware SDK)
• Minimal Structured Logging for Autonomous Vehicles (C++, closed source talk)
• NanoLog (C++11) (Linux C++)
• Percepio Tracealyzer (with TraceRecorder) (Visual Trace Diagnostics)
• Pigweed Trace Tokenized
• Postform (Postponed formatting experiments with string interning in C++, inspired by the defmt Rust crate)
• qpspy (C/C++)
• Real-time binary data logging/tracing toolkit
• SEGGER System View
• Serial-Studio (Data visualisation)
• Tonbandgerät (Small embedded systems tracer with support for bare-metal and FreeRTOS-based targets)
• Traces (API tracing framework for Linux C/C++ applications)
• uLog (RD Poor)
• Zephyr Dictionary Based Logging

Additional comparison material:

• Trice Compare (generated 2025-05-26) - compact generated comparison with related tools
• Logging & Tracing Solutions for Embedded Systems (generated 2026-02-16) - longer generated overview of the broader tool landscape

(back to top)