Files

feat: add nixos_flake_info metric with current and remote revisions

Add a new info metric that exposes the current system's flake revision
and the latest remote revision as labels. This makes it easier to see
exactly which revision is deployed vs available.

Also adds version constant to Go code and extracts it in flake.nix,
providing a single source of truth for the version.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-07 00:16:19 +01:00

3.0 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

nixos-exporter is a Prometheus exporter for NixOS-specific metrics. It exposes system state information that standard exporters don't cover: generation management, flake input freshness, and upgrade status.

Status: Implementation complete.

Build Commands

Run commands through the Nix development shell using nix develop -c:

# Build
nix develop -c go build ./...

# Run tests
nix develop -c go test ./...

# Run single test
nix develop -c go test -run TestName ./path/to/package

# Lint
nix develop -c golangci-lint run

# Vulnerability check
nix develop -c govulncheck ./...

# Test Nix build
nix build

# Run the binary (prefer this over go build + running binary)
# To pass arguments, use -- before them: nix run .#default -- --help
nix run .#default

Testing Procedures

Before committing, run the following checks:

nix develop -c go test ./... - Unit tests
nix develop -c golangci-lint run - Linting
nix develop -c govulncheck ./... - Vulnerability scanning
nix build - Verify nix build works

Architecture

Single binary with pluggable collectors:

nixos-exporter/
├── main.go                 # Entry point, HTTP server on :9971
├── collector/
│   ├── generation.go       # Core metrics (count, current, booted, age, mismatch)
│   └── flake.go            # Flake input freshness metrics (optional)
└── config/
    └── config.go           # YAML + CLI flag handling

Collectors

Generation collector (always enabled): Reads symlinks in /nix/var/nix/profiles/ and /run/current-system to determine generation state.

Flake collector (optional): Parses flake.lock JSON to extract lastModified timestamps per input.

Configuration

Supports YAML config file, CLI flags (--listen, --collector.flake, --flake.lock-path), and NixOS module integration via services.prometheus.exporters.nixos.

Commit Message Format

Use conventional commit format:

feat: add new feature
fix: fix a bug
docs: update documentation
refactor: refactor code without changing behavior
test: add or update tests
chore: maintenance tasks

Version Bumping

Follow semantic versioning:

Patch (0.0.x): Bugfixes
Minor (0.x.0): Non-breaking changes adding features
Major (x.0.0): Breaking changes

Update the const version in main.go. The Nix build extracts the version from there automatically.

When to bump: If any Go code has changed, bump the version before committing. Do this automatically when asked to commit. On feature branches, only bump once per branch (check if version has already been bumped compared to master).

Key Design Decisions

Go chosen for mature Prometheus client library and static binary output
Port 9971 allocated for this exporter
Follows nixpkgs services.prometheus.exporters.* module pattern
No root required - only reads symlinks and files

3.0 KiB Raw Blame History