![Demo](./assets/ns-demo.png) `nix-evaluator-stats`, or "ns" for short, is a pretty visualiser for the Nix evaluator stats export from `NIX_SHOW_STATS` and `NIX_COUNT_CALLS` invocations. It takes the resulting JSON data from your Nix invocation with the relevant variables, and provides a ✨ pretty ✨ dashboard-like visual with the ability to compare your "snapshots" of benchmarks. Besides looking nice, it is helpful in collecting statistics about your Nix commands and tracking performance regressions in subsequent exports. ## Usage NS provides both a web application for pretty visuals, and a terminal client (a TUI) for rendering the statistics from your terminal. ### Web Usage instructions are provided in the initial page. Simply navigate to the site and provide the JSON export (or a file) to render the statistics. The number of rendered fields might differ based on your Nix version or implementation (Lix, Snix, etc.) The classic usage looks like this: ```bash # Invoke a Nix command with NIX_SHOW_STATS=1 $ NIX_SHOW_STATS=1 nix eval nixpkgs#hello -- --option eval-cache false # disable eval-cache for accuracy # Or write to a file directly $ NIX_SHOW_STATS_PATH=stats.json nix eval nixpkgs#hello -- --option eval-cache false ``` 1. Create the JSON export 2. Copy it if printed to stdout 3. Paste or upload it in the input field that appears the first time you visit the site Once you hit "Load", the JSON will be parsed and you'll be looking at a dash board of your export. By using the snapshot feature, i.e., saving a particular analysis you may compare two _named_ analyses at a time. > [!NOTE] > `nix-evaluator-stats` was created in a very short duration, and there might be > UI bugs or areas where UI polish is very clearly missing. Please crate an > issue if the generated graph or the site UI looks off. Thanks :) #### Snapshots Snapshots are an "experimental" (just means they're new and unpolished) feature that lets you save an analysis in your browser storage with a name to be used later on in the comparison view. At least two **named** analyses (i.e., snapshots) are required for an analysis. You can save an analysis as a snapshot from the save button on the bottom right. ## Hacking This project is built with various web technologies. Namely we use Vite, Typescript-React (`.tsx`) and SolidJS for most of our user interfaces. The recommended approach for resolving dependencies is using Nix; a Nix shell is provided, and dependencies can be fetched with `pnpm` while inside the dev shell. ```bash # Run the live server $ pnpm run dev # Build a static site $ pnpm run build ``` If submitting pull requests, please ensure that format (`pnpm run fmt`) and lint (`pnpm run lint`) tasks are ran beforehand. The automated CI will tell you whether your code matches the requirements, but it's a good rule of thumb to do this before submitting your PR. ## License This project is made available under Mozilla Public License (MPL) version 2.0. See [LICENSE](LICENSE) for more details on the exact conditions. An online copy is provided [here](https://www.mozilla.org/en-US/MPL/2.0/).