···11## nod
2233-A simple self-contained daemon to gather statistics on Nix builds and substitutions using structured JSON logs.
33+A simple daemon that collects Nix build and substitution statistics using structured JSON logs.
4455## requirements
6677-- nix 2.30 or later (for `json-log-path` support).
77+- Nix 2.30 or later (`json-log-path` support)
8899## building
10101111-``` bash
1111+```bash
1212cargo build --release
1313```
14141515## usage
16161717-First you must make sure the nod daemon is running.
1717+Start the daemon:
18181919```bash
2020nod daemon
2121```
2222-By default, it listens on `/run/nod/nod.sock` and stores data in `/var/lib/nod/nod.db`.
2323-Manual setup requires write permissions for the socket.
24222525-Then configure nix to output detailed trace logs to the socket.
2323+Point Nix at the socket in `nix.conf`:
26242727-Add the following to your `nix.conf` (usually `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`):
2828-```text
2929-json-log-path = /run/nod/nod.sock
2525+```
2626+json-log-path = /run/user/1000/nod/nod.sock
3027```
31283232-### nixos
2929+Then use Nix normally. View accumulated stats with:
33303434-Add the flake to your inputs and use the provided module:
3131+```bash
3232+nod stats # all time
3333+nod stats -d 7 # last 7 days
3434+nod stats -m 3 # last 3 months
3535+nod stats -y 1 # last year
3636+nod clean # reset the database
3737+```
35383636-```nix
3737-services.nod.enable = true;
3838-```
3939-This handles the socket path, permissions, and `nix.conf` automatically.
3939+## configuration
40404141-Just use Nix as usual:
4242-```bash
4343-nix build nixpkgs#hello
4444-```
4141+| flag | env | default |
4242+|------|-----|---------|
4343+| `--socket` | `NOD_SOCKET` | `$XDG_RUNTIME_DIR/nod/nod.sock` |
4444+| `--db` | `NOD_DB` | `$XDG_DATA_HOME/nod/nod.db` |
45454646-Then view your stats:
4747-```bash
4848-nod stats
4949-```
4646+Both directories are created automatically. The socket path in `nix.conf` must match `--socket`.
50475148## how?
52495353-The daemon uses the `json-log-path` feature introduced in Nix
5454-2.30. Instead of parsing the complex binary worker protocol, it
5555-consumes a structured stream of events directly from the Nix
5656-process. Relevant
5757-[code](https://github.com/NixOS/nix/blob/b4de973847370204cf28fe2092abdd21f25ee0e8/src/libutil/include/nix/util/logging.hh)
5050+Nix 2.30 added `json-log-path`, which writes a stream of structured activity events (start/result/stop) to a file or Unix socket while a build runs. nod listens on that socket, tracks in-flight activities by ID, and on each stop event inserts a completed row into a local SQLite database. `nod stats` queries that database through the daemon.
5151+5252+Relevant Nix source: [logging.hh](https://github.com/NixOS/nix/blob/b4de973847370204cf28fe2092abdd21f25ee0e8/src/libutil/include/nix/util/logging.hh)