mirror of
https://github.com/NotAShelf/nix-evaluator-stats.git
synced 2026-04-27 12:25:20 +00:00
NotAShelf
6484ded3d7
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Ib70b7d5101bb0e2b103e96770965570f6a6a6964
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
<!-- markdownlint-disable MD033 MD041 -->
|
|
|
|
<div align="center">
|
|
<h1 id="header">nix-evaluator-stats</h1>
|
|
<a alt="CI Status" href="https://github.com/NotAShelf/nix-evaluator-stats">
|
|
<img
|
|
src="https://github.com/NotAShelf/nix-evaluator-stats/actions/workflows/check.yml/badge.svg"
|
|
alt="Lints & Formatting"
|
|
/>
|
|
</a>
|
|
<a alt="Build & Deploy" href="https://notashelf.github.io/nix-evaluator-stats/">
|
|
<img
|
|
src="https://github.com/NotAShelf/nix-evaluator-stats/actions/workflows/deploy.yml/badge.svg"
|
|
alt="License"
|
|
/>
|
|
</a>
|
|
</div>
|
|
|
|
<!-- markdownlint-enable MD033 -->
|
|
|
|
|
|
|
|
`nix-evaluator-stats`, or "`ns`", 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 with the comparison feature with snapshot of
|
|
your analyses.
|
|
|
|
## Usage
|
|
|
|
NS is primarily a web application for pretty visuals, with a terminal client
|
|
(both a CLI and a TUI) planned for rendering statistics or sharing your analyses
|
|
with others.
|
|
|
|
### Web
|
|
|
|
<!--markdownlint-disable MD059-->
|
|
|
|
You can find the site [here](https://notashelf.github.io/nix-evaluator-stats/).
|
|
|
|
<!--markdownlint-enable MD059-->
|
|
|
|
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:
|
|
|
|
<!-- markdownlint-disable MD013 -->
|
|
|
|
```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
|
|
```
|
|
|
|
<!-- markdownlint-enable MD013 -->
|
|
|
|
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.
|
|
|
|
#### Snapshots
|
|
|
|
Snapshots are a new 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 can analysis as a snapshot from the save button on the bottom
|
|
right. Alternatively, you can visit the "compare" page and paste your JSON
|
|
directly.
|
|
|
|
## 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
|
|
|
|
<!-- markdownlint-disable MD059 -->
|
|
|
|
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/).
|
|
|
|
<!-- markdownlint-enable MD059 -->
|