Guider: a system profiler that keeps the data on the machine

The design decision: nothing leaves the machine

The part of Guider's design that most affects how you would use it is stated in the overview rather than buried. Instead of streaming monitoring data to an external server in real time, Guider retains collected data in its internal buffer and automatically generates analysis reports upon event detection.

That is a different architecture from the one most people picture when they think of a monitoring tool. The common pattern is a small agent on each machine that ships numbers to a central collector, where dashboards aggregate them. Guider inverts that: the data stays where it was collected, and the output is a report plus interactive SVG visualisations that you open in a browser locally.

The reasons a tool like that is useful are practical. A performance investigation is often exploratory and local, you are looking at one machine, one process, one period. Shipping everything to a server costs bandwidth and adds a dependency on infrastructure that may itself be the thing under suspicion. A tool that keeps the data in its own buffer can run on a device with no network, on an embedded target, or on a machine where the network is the suspected bottleneck.

The continuous monitoring service that sits on top of this is described as proactive rather than reactive. It manages events based on predefined thresholds and conditions. Thresholds cover metrics such as CPU load, memory usage and I/O latency. Conditions are logical rules that combine thresholds with system states to trigger specific actions, and the actions are event handlers that automatically execute built-in commands to collect data or mitigate the issue.

So the shape is: something crosses a line, and Guider immediately runs the command that captures what was happening at that moment. That is a more useful design than a dashboard that only tells you a number was high at some point in the past.

One tool covering monitoring, profiling, tracing, control and logging

The feature list is organised into categories, and the categories tell you the intended scope. It is a single tool rather than a suite.

Monitoring covers Resource, Task, Function, File, WSS, Log, IPC, Container and Event. Profiling covers Resource, File, Function and Event. Tracing covers Resource, Leak, Signal, Function and Event. Control covers Resource, Task, Signal, Affinity, Scheduler and Hook. Logging covers Kernel, Syslog, Ftrace, DLT, Journal and Android. Visualisation covers Line Graph, Stacked Graph, Flame Graph, Bar Graph, Violin Plot and Histogram. Testing covers CPU, Memory, Storage and Network. Utilities covers Duplicated Memory, Property, Pager, Diff, Watch, Systemd, binutils and bugreport.

Several of these choices are worth pausing on. Control of affinity, scheduler and signals is a different level of intervention than most profilers offer, and it means Guider can change system state as well as observe it. The Hook control command in particular suggests it can install its own hooks, which pairs naturally with the trace and profile categories.

The DLT and Journal log sources are a tell about the target market. DLT is the automotive Diagnostic Log and Trace protocol, and Journal is systemd's structured log, so this is a tool built by someone who works on embedded and automotive Linux as well as on desktop servers. The container monitoring entry says the same thing about containers.

The visualisation list includes a violin plot, which is not a common choice in system tooling, and the report categories cover peaks, process crashes, kernel panics and ANRs. The last of those is an Android concept, which is the clearest statement that Guider targets both platforms rather than Linux alone.

A command API over TCP and Unix sockets

Guider exposes a command-based API over TCP and UDS, and the README describes the intent as enabling Linux and Android application developers to access and visualise system performance data easily.

The API is described in three modes, and the distinction between them is the useful part. Oneshot is a single command execution with an immediate JSON-formatted response. Stream is a persistent session for continuous command output streaming, with monitoring updates given as the example. Control is a command interface to start, stop, configure and manage Guider services remotely.

Oneshot plus JSON is the mode that makes Guider useful as a component rather than a tool you run by hand. A script or an application can ask for a measurement and parse the answer, which means Guider can sit behind your own reporting, your own dashboard, or a test that asserts on a metric. The stream mode is the one you would use for a live view, and the control mode is the one you would use to script a session.

The claim that it works independently without requiring external infrastructure follows from the buffer-and-report design. There is no server component to run, which is a genuine advantage in an environment where the only thing you have is the device.

The repository structure reflects the API being a first-class feature rather than a script bolted on. There is an openapi/ directory, which is where an OpenAPI description would live, and an mcp/ directory, which suggests a Model Context Protocol surface alongside the TCP and UDS interfaces. If you are evaluating the project for agent tooling rather than for a dashboard, that mcp directory is the place to look.

What the output actually looks like

The README shows one example, the top command, and it is worth reading the output carefully because it shows how much the tool tracks at once.

    $ python3 guider/guider.py top -a

The top line carries a timestamp, the interval, the context switch count, the number of tasks, the load averages split three ways, and the RAM and swap usage. It also reports the number of live and total processes, the interrupt count and the core count.

The second line is the pressure stall information, with some and full percentages broken down per resource. This is the modern Linux pressure stall accounting, the mechanism that tells you not just that a task was slow but that it was waiting because the kernel had no CPU, memory or I/O headroom. A profiler that surfaces that unprompted is reporting a category of problem that a plain CPU percentage hides.

The third line is the hardware counters: cycles, instructions retired, instructions per cycle, cache misses as a count and a percentage, branch misses, clock cycles, and minor and major page faults. Cache miss rate and branch miss rate are the two numbers that usually decide whether a workload is bound by memory latency or by branch prediction.

The -a flag is what makes it the wide view. The design goal stated in the advantages list is precise measurements in counts, execution time in microseconds and data size in bytes, and this output is what that looks like in practice: raw counters rather than a single derived score.

Platform coverage is broad, but the kernel is the boundary

The support table is unusually specific for a project of this kind, and it divides into three tiers rather than claiming everything works.

Linux distros listed as supported are Ubuntu, CentOS and RHEL. A separate tier covers Android, ccOS, webOS, Tizen and AGL, which is a set of embedded and automotive platforms. A third tier is Windows and macOS with limited support.

On architecture, the list is x86, x64, ARM, AArch64 and RISC-V for the CPU. That is a real breadth, and RISC-V in the list is worth noting given how new that target is for embedded work.

The README's own summary is that Guider supports a wide range of platforms based on the Linux kernel and architectures, and the phrasing is doing careful work. The dependency is on the Linux kernel, not on a distribution, which is why the embedded platforms appear: they run Linux kernels with different configurations.

That points at the practical constraint, and the README has a section for it. There is a Kernel Configuration section in the table of contents, alongside the build and installation section, which tells you that some of the commands depend on kernel features being compiled in. The tracing, hook and control categories are the ones that care most, because the kernel interfaces they use are the ones that get left out of a small embedded build.

The build and installation details sit behind that section heading rather than on the page. What the packaging tells you is more concrete: setup.py declares the package as version 3.9.9, GPL2, with a console script named guider, a man page installed to share/man/man1, a configuration file installed to share/guider, and psutil as the only install requirement, and that requirement is conditional on the platform not being Linux.

Ten years of field use, and a release rhythm that slowed

The README claims the project has evolved over ten years, from 2015 to 2025, through continuous development, field usage and community feedback. Ten years of field use on a profiler is meaningful in a specific way: the hard parts of system profiling are not the measurements, they are the edge cases where a measurement breaks a kernel version, a container runtime, or a driver.

The version history tells a more cautious story. The recent releases are versions/3.9.9 from 2025-05-23, versions/3.9.8 from 2021-03-27 and versions/3.9.7 from 2020-03-08. So 3.9.7 to 3.9.8 spans a year, 3.9.8 to 3.9.9 spans four, and the numbering has been at 3.9.x for a long time. The current package version in setup.py matches 3.9.9, which is the newest tag.

The last push to the repository was on 2026-10-20, so the source is being worked on, and the repository is not archived. The repository also carries a CLAUDE.md, a CONTRIBUTING.md, a Documentation/ directory, a patch/ directory, a utils/ directory, a guider.service systemd unit file, a man page and a guider.rc configuration file, plus a guider_3.9.9.bb file that is a BitBake recipe for embedded builds. That last one is a good indicator of the target audience.

Two project-specific details are worth mentioning for anyone browsing the source. The home page for the documentation is a GitHub Pages site, guider.html, and the package is on PyPI as well as on SourceForge, with a Gitter chat linked from the README. The presence of both PyPI and SourceForge distributions, with a BitBake recipe on top, is the pattern of a tool that gets installed on everything from a developer laptop to an embedded device.

Editorial conclusion

Adopt Guider if you need to profile a Linux or Android box on the spot, especially one you cannot send data off, because it keeps measurements in a local buffer, produces reports and SVG visualisations on event detection, and speaks a command API over TCP or Unix sockets. Do not adopt it as a long-lived fleet monitoring system, since the design is a buffer-and-report service rather than a streaming pipeline to a central collector. Before you commit, read the kernel configuration section of the documentation, because several of its commands depend on what the kernel was built with, and run the top command on a machine you own before you build anything on top of the API.

Frequently asked questions

Official sources

1. iipeace/guider on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases