If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/prometheus/node_exporter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 22+ active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live prometheus/node_exporter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/prometheus/node_exporter.

What it runs against: a local clone of prometheus/node_exporter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in prometheus/node_exporter | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of prometheus/node_exporter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/prometheus/node_exporter.git
#   cd node_exporter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of prometheus/node_exporter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "prometheus/node_exporter(\\.git)?\\b" \\
  && ok "origin remote is prometheus/node_exporter" \\
  || miss "origin remote is not prometheus/node_exporter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "collector/collector.go" \\
  && ok "collector/collector.go" \\
  || miss "missing critical file: collector/collector.go"
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "collector/cpu_linux.go" \\
  && ok "collector/cpu_linux.go" \\
  || miss "missing critical file: collector/cpu_linux.go"
test -f "collector/filesystem_linux.go" \\
  && ok "collector/filesystem_linux.go" \\
  || miss "missing critical file: collector/filesystem_linux.go"
test -f "collector/device_filter.go" \\
  && ok "collector/device_filter.go" \\
  || miss "missing critical file: collector/device_filter.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/prometheus/node_exporter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Prometheus Node Exporter is a Go-based agent that scrapes hardware and OS metrics from *NIX systems (Linux, BSD, Solaris, AIX, etc.) and exposes them via HTTP on port 9100 in Prometheus text format. It uses pluggable collectors—each implementing metrics for CPU, memory, disk, network, thermal, and system-level telemetry—without requiring agent installation on monitored machines. Single-binary monolith: collector/ directory contains ~40 platform-specific and cross-platform collectors (e.g., collector/cpu_linux.go, collector/cpu_darwin.go), each registering metrics via the collector.Collector interface defined in collector/collector.go. Main entry point infers from typical Go project structure. Collectors are selectively enabled/disabled via --collector.<name> CLI flags, making the binary adaptable per deployment.

DevOps engineers and SREs who run Prometheus monitoring stacks and need host-level observability; systems integrators deploying edge monitoring in containerized and bare-metal environments; platform teams building internal observability infra for thousands of nodes across heterogeneous OS targets.

Production-ready and actively maintained. Broad adoption (official Prometheus community project), comprehensive test coverage across multiple platforms (see collector/*_test.go and GitHub Actions workflows for Linux, BSD, CI), and frequent dependency updates (Dependabot config present). Last Go version is 1.25.0 indicating recent activity.

Low risk for core functionality but platform-specific: each OS collector (cpu_linux.go, cpu_darwin.go, etc.) is independently maintained, creating test surface area and potential gaps. High cgo dependency count (btrfs, perf-utils, rtnetlink) increases build fragility. Single primary maintainer pattern typical of Prometheus community projects; breaking changes to metric names require careful coordination with operator deployments.

Active maintenance: recent dependency updates (go-systemd, netlink, client_golang 1.23.2), platform expansion (bcachefs_linux.go added recently per file list), and CI hardening (separate BSD workflow, govulncheck integration). Issue template and security policy in place suggest structured triage.

git clone https://github.com/prometheus/node_exporter.git
cd node_exporter
make build
./node_exporter --help
# Runs on http://localhost:9100/metrics by default

Daily commands:

make build                          # Compiles binary to node_exporter
./node_exporter                     # Starts HTTP server on :9100
./node_exporter --collector.cpu     # Enable only CPU collector
./node_exporter --path.rootfs=/host # For containerized host monitoring

• collector/collector.go — Core collector interface and registry—defines how all metrics collectors are implemented and registered; essential for understanding the plugin architecture.
• main.go — Application entry point and CLI flag setup—controls which collectors are enabled and exporter initialization; required to understand startup flow.
• collector/cpu_linux.go — Linux CPU metrics implementation—largest collector by complexity; demonstrates the pattern for OS-specific metric extraction used throughout the codebase.
• collector/filesystem_linux.go — Linux filesystem metrics—shows mount point discovery and device filtering patterns replicated across other collectors.
• collector/device_filter.go — Device filtering abstraction used by diskstats, filesystem, and other collectors—critical for understanding how metrics can be filtered by include/exclude patterns.
• Makefile — Build configuration and cross-platform compilation targets—defines how the exporter is built for multiple OS/arch combinations.
• .promu.yml — Prometheus build tool configuration—controls release artifacts and versioning strategy.

Add a new system metrics collector

1. Create a new file following the pattern collector/METRICNAME_PLATFORM.go (e.g., collector/thermal_linux.go) (collector/thermal_linux.go)
2. Implement the Collector interface with Name(), Help(), Describe(), and Collect() methods (collector/collector.go)
3. Register the collector in main.go by adding it to the collectors map with NewXXX() constructor (main.go)
4. Add a flag for enabling/disabling: kingpin.Flag('collector.XXX', 'Enable XXX collector').Default('true').Bool() (main.go)
5. Add unit tests in collector/XXX_test.go using fixtures from collector/fixtures/ (collector/thermal_linux_test.go)
6. Update collector/fixtures/e2e-output.txt with expected metric output for integration tests (collector/fixtures/e2e-output.txt)

Add a new platform variant of an existing metric

1. Review existing implementation (e.g., collector/diskstats_linux.go) to understand metric structure (collector/diskstats_common.go)
2. Create platform-specific file (e.g., collector/diskstats_aix.go) implementing the same metrics from AIX syscalls (collector/diskstats_aix.go)
3. Build flags in collector/diskstats_aix.go to conditionally compile on GOOS=aix (collector/diskstats_aix.go)
4. Register collector in main.go with platform conditional logic (main.go)
5. Add fixtures and tests for the new platform variant (collector/fixtures/e2e-output-aix.txt)

Add device filtering to an existing collector

1. Import the device filter package in your collector file (collector/diskstats_linux.go)
2. Initialize filters in collector constructor using device_filter.NewFilter() (collector/device_filter.go)
3. Add command-line flags for include/exclude patterns via kingpin in main.go (main.go)
4. Apply filters in the Collect() method before emitting metrics: if !c.filter.Match(deviceName) continue (collector/diskstats_linux.go)
5. Add test cases to collector/device_filter_test.go covering include/exclude patterns (collector/device_filter_test.go)

Handle a new /proc file or sysfs interface

1. Review similar collector to understand error handling pattern (e.g., filesystem_linux.go reads /proc/mounts) (collector/filesystem_linux.go)
2. Create or update your collector to read from /proc or /sys with proper error handling and fallbacks (collector/cpu_linux.go)
3. Add test fixtures in collector/fixtures/proc/ or collector/fixtures/sys/ directories matching the file structure (collector/fixtures/proc/1/stat)
4. Write unit tests that parse fixture files instead of live /proc to avoid platform dependencies (collector/cpu_linux_test.go)

• Go (1.25.0) — Cross-platform compilation, single binary, minimal runtime overhead, strong standard library for syscalls and parsing
• Prometheus client library (implied by dependency graph) — Standardized metrics export format (text format), integration with Prometheus scraping protocol
• kingpin/v2 CLI framework — Simple flag parsing for enabling/disabling collectors and configuring filters per-deployment
• cgo bindings (devstat_freebsd.c, perf-utils, btrfs, etc.) — Access to OS-specific APIs (FreeBSD devstat, Linux perf events, Btrfs ioctl) not exposed in Go stdlib
• netlink/rtnetlink for network metrics — Direct kernel socket communication for real-time network interface stats without parsing /proc

• Plugin architecture via collector.Collector interface—each metric type is a separate collector
  • Why: undefined
  • Consequence: undefined

1. Cgo compilation: collectors using C bindings (btrfs, perf-utils) require gcc and platform headers; musl vs glibc affects binary portability. 2. /proc and /sys paths are hardcoded; --path.rootfs must be set for containerized deployments or metrics read from host namespace. 3. Platform-specific test failures silent in CI if test file missing (e.g., cpu_windows_test.go doesn't exist; Windows support deferred to windows_exporter). 4. Metric name stability is critical—breaking changes require Prometheus operator/alert rule updates across all users. 5. Some collectors require elevated caps (timex needs SYS_TIME) or specific namespaces (network collectors need /sys/class/net access).

• Pluggable collector pattern — Node exporter's architecture relies on implementing and registering collectors that conform to a shared interface; understanding this pattern is essential to extending the exporter with new metrics
• Procfs and sysfs parsing — Most Linux collectors extract metrics by reading pseudo-filesystems (/proc/stat, /sys/class/net); this is the core data source and parsing logic for ~30 collectors
• Prometheus text exposition format — Node exporter outputs metrics in this specific text format (HELP, TYPE, samples); understanding the format is necessary to verify collector correctness and debug scraping issues
• Cgroup and namespace isolation — Docker/Kubernetes deployments require careful namespace configuration (host PID, network namespace access); node_exporter must be aware of cgroup v2 and namespace limits to avoid reading container metrics instead of host
• Build tags and platform abstraction — Node exporter uses Go build tags (//+build linux, darwin, etc.) to conditionally compile collectors per OS; this pattern is essential for maintaining 6+ OS-specific code paths in a single binary
• Metric cardinality and label dimensions — Collectors must be careful with unbounded labels (e.g., per-interface or per-device metrics) to avoid exploding cardinality in time-series databases; device_filter.go manages this through allowlisting
• seccomp and capability filtering — Some collectors (timex) require Linux capabilities (SYS_TIME) that may be blocked in hardened or containerized environments; deployment requires careful cap-add configuration

• prometheus/prometheus — Time-series database and scraping engine that consumes node_exporter metrics; essential for understanding the full observability stack
• prometheus/client_golang — Prometheus metrics instrumentation library used by node_exporter to define and expose metrics; fundamental dependency
• prometheus-community/windows_exporter — Windows analog to node_exporter; covers same host metrics for Windows systems using WMI and Performance Counters
• prometheus/procfs — Go library for parsing /proc and /sys filesystems; directly used by node_exporter collectors for metric extraction
• prometheus-community/ansible — Ansible role for automated node_exporter deployment, mentioned in README as primary deployment method for ops teams

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for collector/device_filter.go

The device_filter.go file exists but device_filter_test.go appears minimal based on the file listing. Device filtering is critical for controlling which hardware metrics are exported across multiple collectors (diskstats, ethtool, etc.). Robust tests would prevent regressions in filtering logic across different platforms and device types.

• [ ] Review collector/device_filter.go and device_filter_test.go to identify untested code paths
• [ ] Add test cases for include/exclude patterns, regex matching, and edge cases (empty filters, special characters)
• [ ] Add platform-specific test cases since device naming differs across Linux, BSD, Solaris
• [ ] Add tests for filter interaction with real /sys/block and /sys/class device structures
• [ ] Verify test coverage reaches >90% for this critical shared utility

Add GitHub Actions workflow for AIX and Solaris platform testing

The repo supports multiple platforms (Linux, BSD, Solaris, AIX, DragonFly) but current workflows only test Linux (.github/workflows/ci.yml) and BSD (.github/workflows/bsd.yml). AIX and Solaris collectors (cpu_aix.go, boot_time_solaris.go, cpufreq_solaris.go, diskstats_aix.go) lack automated testing. Adding cross-platform CI would catch platform-specific bugs early.

• [ ] Create .github/workflows/solaris.yml using available Solaris CI runners or containers
• [ ] Create .github/workflows/aix.yml with appropriate AIX testing setup
• [ ] Configure workflows to run platform-specific collector tests and build verification
• [ ] Ensure Makefile.common supports building for these platforms in CI context
• [ ] Add badges to README.md for Solaris and AIX workflow status

Add integration tests for ethtool_linux.go with mock network interfaces

The ethtool_linux.go collector is complex with its own test file, but based on the breadth of Linux network features (ethtool, wifi, bonding, conntrack), there are likely edge cases uncovered. This collector frequently breaks on new kernel versions with new ethtool features. Mock-based integration tests would improve reliability.

• [ ] Review ethtool_linux_test.go for gaps in feature coverage (autoneg, pause frames, ring buffers, timestamps)
• [ ] Create mock ethtool command outputs for various network devices (ethernet, wifi, bonded, vlan)
• [ ] Add tests for parsing failures and malformed ethtool output to ensure graceful degradation
• [ ] Add tests for permission denied scenarios (non-root execution) with appropriate error handling
• [ ] Test interaction with bonding_linux.go and wifi collectors to ensure no metric conflicts

• Add test coverage for collector/buddyinfo.go (exists but likely untested); write unit tests parsing sample /proc/buddyinfo output similar to patterns in cpu_linux_test.go.
• Extend collector/device_filter.go to support regex inclusion patterns (currently only blocklist); useful for large node deployments filtering specific disk/NIC prefixes.
• Document missing collector flags in CLI help output; add descriptions and examples for --collector.cgroups, --collector.bonding in code or help text generation.

The prometheus/node_exporter codebase demonstrates a solid security posture with several best practices implemented: non-root container execution, no obvious hardcoded secrets, and use of well-maintained dependencies. However, there are areas for improvement: the Go version specification appears incorrect, base image tags should be pinned to specific versions rather than ':latest', and the generic 'nobody' user could be replaced with a dedicated service account. The project has a documented security reporting policy in SECURITY.md, which is positive. Regular dependency audits and monitoring through govulncheck (already in CI/CD) are evident. No critical injection vulnerabilities or obvious credential exposure was identified in the provided file structure and content samples.

• Medium · Outdated Go Version — go.mod. The go.mod file specifies go 1.25.0, which is a future/unreleased version. This is unusual and may indicate a misconfiguration or development environment issue. Production builds should use stable, released Go versions. Fix: Update go.mod to use a stable released Go version (e.g., go 1.23.x or 1.24.x). Verify the correct target version for your release cycle.
• Medium · Dependency: golang.org/x/sys v0.42.0 — go.mod - golang.org/x/sys v0.42.0. The golang.org/x/sys dependency is pinned to v0.42.0. While this is a mature package, system-level packages should be regularly updated to receive security patches and bug fixes. No specific CVE identified, but this warrants periodic review. Fix: Regularly audit and update golang.org/x/sys to the latest stable version. Run 'go get -u golang.org/x/sys' and test thoroughly before deployment.
• Low · Container runs as 'nobody' user — Dockerfile - USER nobody. While running as a non-root user (nobody) is a security best practice, the 'nobody' user is a generic system account that exists across all Unix-like systems. In some configurations, this could potentially allow privilege escalation or cross-container attacks in shared environments. Fix: Consider creating a dedicated non-root user for the node_exporter service instead of using the generic 'nobody' account. This provides better isolation and security posture.
• Low · Build stage uses dynamic base image — Dockerfile - FROM quay.io/prometheus/busybox-${OS}-${ARCH}:latest. The Dockerfile uses 'quay.io/prometheus/busybox-${OS}-${ARCH}:latest' with dynamic OS and ARCH variables. Using ':latest' tags can introduce non-deterministic builds if the base image is updated unexpectedly. Fix: Pin the base image to a specific version tag (e.g., ':1.35' or ':1.35-glibc') instead of ':latest' for reproducible, deterministic builds and better supply chain security.
• Low · Incomplete dependency list in go.mod — go.mod - indirect dependencies section. The indirect dependencies section appears truncated in the provided go.mod content. The last line 'github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f /' is incomplete, which could indicate a malformed module file. Fix: Verify the go.mod file is complete and well-formed. Run 'go mod tidy' to ensure all dependencies are properly listed and validated.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.