# rostedt/trace-cmd architecture

> Architecture diagram of the GitHub repository rostedt/trace-cmd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rostedt/trace-cmd
- Repository: https://github.com/rostedt/trace-cmd

## Overview

trace-cmd is a Linux tracing toolkit and libtracecmd library. Its central workflow configures kernel tracing, records events to trace.dat, then reads and analyzes the resulting trace. The tree also documents command-line tools, Python interfaces, and live-agent/network support. The graph links only relationships visible in excerpts or explicitly documented by the README; other command-dispatch and analysis relationships are left unconnected where source was not shown.

Main entry points: [`lib/trace-cmd/trace-input.c`](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-input.c) (Trace reader), [`tracecmd/trace-record.c`](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-record.c) (Record tracing), [`lib/trace-cmd/trace-compress.c`](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress.c) (Compression), [`python/tracecmd.py`](https://github.com/rostedt/trace-cmd/blob/master/python/tracecmd.py) (Python interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and transport"]
  node_record["Record tracing<br/>[trace-record.c]"]
  node_agent["Trace agent<br/>[trace-agent.c]"]
  node_listen["Live listener<br/>[trace-listen.c]"]
  node_message["Message transport<br/>[trace-msg.c]"]
  node_timesync["Clock synchronization<br/>[trace-timesync.c]"]
  node_ptp["PTP synchronization"]
end

subgraph group_format["Trace file library"]
  node_output["Trace writer<br/>[trace-output.c]"]
  node_input["Trace reader<br/>[trace-input.c]"]
  node_compression["Compression<br/>[trace-compress.c]"]
  node_zlib["Zlib backend"]
  node_zstd["Zstd backend"]
  node_publicapi["Library API<br/>[trace-cmd.h]"]
  node_tracefile[("trace.dat")]
end

subgraph group_analysis["Trace analysis"]
  node_profile["Trace profiling<br/>[trace-profile.c]"]
  node_read["Trace reading<br/>[trace-read.c]"]
  node_hist["Event histograms<br/>[trace-hist.c]"]
  node_sqlhist["SQL histograms<br/>[trace-sqlhist.c]"]
  node_stat["Trace statistics<br/>[trace-stat.c]"]
  node_split["Trace splitting<br/>[trace-split.c]"]
  node_dump["Trace dump<br/>[trace-dump.c]"]
end

subgraph group_interfaces["User interfaces"]
  node_python["Python interface<br/>[tracecmd.py]"]
  node_eventviewer["Event viewer<br/>[event-viewer.py]"]
  node_pygui["Python GUI<br/>[tracecmdgui.py]"]
  node_cli["trace-cmd CLI<br/>[trace-cmd.c]"]
end

node_user(("Operator"))

node_user -->|"starts recording"| node_record
node_record -->|"writes trace data"| node_output
node_record -.->|"uses live transport"| node_message
node_agent -.->|"exchanges messages"| node_message
node_listen -.->|"handles messages"| node_message
node_record -.->|"synchronizes clocks"| node_timesync
node_timesync -.->|"supports PTP"| node_ptp
node_output -->|"writes file"| node_tracefile
node_tracefile -->|"reads file"| node_input
node_input -->|"decodes compression"| node_compression
node_compression -.->|"selects backend"| node_zlib
node_compression -.->|"selects backend"| node_zstd
node_publicapi -->|"exposes reader"| node_input
node_user -.->|"runs commands"| node_cli
node_read -->|"reads trace events"| node_input
node_profile -->|"analyzes trace"| node_input
node_hist -.->|"analyzes trace"| node_input
node_sqlhist -.->|"analyzes trace"| node_input
node_stat -.->|"inspects trace"| node_input
node_split -.->|"processes trace"| node_input
node_dump -->|"processes trace"| node_input
node_python -->|"reads events"| node_input
node_eventviewer -->|"uses interface"| node_python
node_pygui -->|"uses interface"| node_python

click node_record "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-record.c"
click node_agent "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-agent.c"
click node_listen "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-listen.c"
click node_message "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-msg.c"
click node_timesync "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-timesync.c"
click node_ptp "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-timesync-ptp.c"
click node_output "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-output.c"
click node_input "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-input.c"
click node_compression "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress.c"
click node_zlib "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress-zlib.c"
click node_zstd "https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress-zstd.c"
click node_publicapi "https://github.com/rostedt/trace-cmd/blob/master/include/trace-cmd/trace-cmd.h"
click node_profile "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-profile.c"
click node_read "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-read.c"
click node_hist "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-hist.c"
click node_sqlhist "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-sqlhist.c"
click node_stat "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-stat.c"
click node_split "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-split.c"
click node_dump "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-dump.c"
click node_python "https://github.com/rostedt/trace-cmd/blob/master/python/tracecmd.py"
click node_eventviewer "https://github.com/rostedt/trace-cmd/blob/master/python/event-viewer.py"
click node_pygui "https://github.com/rostedt/trace-cmd/blob/master/python/tracecmdgui.py"
click node_cli "https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-cmd.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_record,node_agent,node_listen,node_message,node_timesync,node_ptp toneBlue
class node_output,node_input,node_compression,node_zlib,node_zstd,node_publicapi,node_tracefile toneAmber
class node_profile,node_read,node_hist,node_sqlhist,node_stat,node_split,node_dump toneMint
class node_python,node_eventviewer,node_pygui,node_cli toneRose
class node_user toneIndigo
```

## Components

### Capture and transport

- [Record tracing](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-record.c): `tracecmd/trace-record.c`
- [Trace agent](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-agent.c): `tracecmd/trace-agent.c`
- [Live listener](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-listen.c): `tracecmd/trace-listen.c`
- [Message transport](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-msg.c): `lib/trace-cmd/trace-msg.c`
- [Clock synchronization](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-timesync.c): `lib/trace-cmd/trace-timesync.c`
- [PTP synchronization](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-timesync-ptp.c): `lib/trace-cmd/trace-timesync-ptp.c`

### Trace file library

- [Trace writer](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-output.c): `lib/trace-cmd/trace-output.c`
- [Trace reader](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-input.c): `lib/trace-cmd/trace-input.c`
- [Compression](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress.c): `lib/trace-cmd/trace-compress.c`
- [Zlib backend](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress-zlib.c): `lib/trace-cmd/trace-compress-zlib.c`
- [Zstd backend](https://github.com/rostedt/trace-cmd/blob/master/lib/trace-cmd/trace-compress-zstd.c): `lib/trace-cmd/trace-compress-zstd.c`
- [Library API](https://github.com/rostedt/trace-cmd/blob/master/include/trace-cmd/trace-cmd.h): `include/trace-cmd/trace-cmd.h`
- **trace.dat**

### Trace analysis

- [Trace profiling](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-profile.c): `tracecmd/trace-profile.c`
- [Trace reading](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-read.c): `tracecmd/trace-read.c`
- [Event histograms](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-hist.c): `tracecmd/trace-hist.c`
- [SQL histograms](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-sqlhist.c): `tracecmd/trace-sqlhist.c`
- [Trace statistics](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-stat.c): `tracecmd/trace-stat.c`
- [Trace splitting](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-split.c): `tracecmd/trace-split.c`
- [Trace dump](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-dump.c): `tracecmd/trace-dump.c`

### User interfaces

- [Python interface](https://github.com/rostedt/trace-cmd/blob/master/python/tracecmd.py): `python/tracecmd.py`
- [Event viewer](https://github.com/rostedt/trace-cmd/blob/master/python/event-viewer.py): `python/event-viewer.py`
- [Python GUI](https://github.com/rostedt/trace-cmd/blob/master/python/tracecmdgui.py): `python/tracecmdgui.py`
- [trace-cmd CLI](https://github.com/rostedt/trace-cmd/blob/master/tracecmd/trace-cmd.c): `tracecmd/trace-cmd.c`

### Other components

- **Operator**

## Connections

- Operator → Record tracing: starts recording
- Record tracing → Trace writer: writes trace data (evidence: `tracecmd/trace-record.c`)
- Record tracing → Message transport: uses live transport
- Trace agent → Message transport: exchanges messages
- Live listener → Message transport: handles messages
- Record tracing → Clock synchronization: synchronizes clocks
- Clock synchronization → PTP synchronization: supports PTP
- Trace writer → trace.dat: writes file
- trace.dat → Trace reader: reads file (evidence: `lib/trace-cmd/trace-input.c`)
- Trace reader → Compression: decodes compression (evidence: `lib/trace-cmd/trace-input.c`)
- Compression → Zlib backend: selects backend
- Compression → Zstd backend: selects backend
- Library API → Trace reader: exposes reader (evidence: `include/trace-cmd/trace-cmd.h`)
- Operator → trace-cmd CLI: runs commands
- Trace reading → Trace reader: reads trace events (evidence: `tracecmd/trace-read.c`)
- Trace profiling → Trace reader: analyzes trace (evidence: `tracecmd/trace-profile.c`)
- Event histograms → Trace reader: analyzes trace
- SQL histograms → Trace reader: analyzes trace
- Trace statistics → Trace reader: inspects trace
- Trace splitting → Trace reader: processes trace
- Trace dump → Trace reader: processes trace (evidence: `tracecmd/trace-dump.c`)
- Python interface → Trace reader: reads events (evidence: `python/tracecmd.py`)
- Event viewer → Python interface: uses interface (evidence: `python/event-viewer.py`)
- Python GUI → Python interface: uses interface (evidence: `python/tracecmdgui.py`)
