From bfb7e5cfa0d096672dd99459c6fc0d259adef6d0 Mon Sep 17 00:00:00 2001 From: Jan Kurik Date: Thu, 7 May 2026 07:21:36 +0200 Subject: [PATCH 1/6] qa: unset LC_ALL in the check script to fix locale-dependent sort order When LC_ALL is set in the caller's environment (e.g. LC_ALL=en_US.utf8), it overrides any per-command LC_COLLATE=POSIX setting used inside individual QA tests, causing locale-sensitive sort ordering instead of the expected POSIX byte-value ordering. This manifests as spurious output mismatches in tests such as 821/1663 where metric names are enumerated via "LC_COLLATE=POSIX sort". Unsetting LC_ALL at the start of the check script removes the inherited override while still allowing individual tests to apply their own per-command locale settings (e.g. "LC_COLLATE=en_US.utf8 sort") as intended by their authors. --- qa/check | 3 +++ 1 file changed, 3 insertions(+) diff --git a/qa/check b/qa/check index ac49b51bfe..9ef4e466f3 100755 --- a/qa/check +++ b/qa/check @@ -21,6 +21,9 @@ __aborted=true myname=`basename $0` __scriptname=$myname # a synonym +# Ensure LC_ALL is not set to allow locale-dependent sort order +unset LC_ALL + # lock (and PID) file to prevent concurrent QA execution # CHECKLOCK=/tmp/PCP-QA-LOCK From 66fbbc50a610d900c7dedd03439523574dc641f9 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 20 Apr 2026 16:14:56 -0400 Subject: [PATCH 2/6] Make it easier for AI tools to find the tests in qa directory --- tests | 1 + 1 file changed, 1 insertion(+) create mode 120000 tests diff --git a/tests b/tests new file mode 120000 index 0000000000..a483eac5ef --- /dev/null +++ b/tests @@ -0,0 +1 @@ +qa \ No newline at end of file From 7b31894ab33a179fdde0407a04705e92a8be461a Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 27 Apr 2026 17:06:44 -0400 Subject: [PATCH 3/6] docs: Provide some headers for the README.md and pointers to additional docs Make it a bit simpler for people (and AI) directly looking at the git repository README.md to get started installing and building PCP and locating the documentation. --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 571fe6b39c..6a237178b6 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,25 @@ supporting both live and retrospective analysis. The distributed PCP architecture makes it especially useful for those seeking centralized monitoring of distributed processing. +## Installation + +For common Linux distributions with prebuilt Performance Co-Pilot packages +you can follow the [Quick install instructions] +[https://pcp.readthedocs.io/en/latest/HowTos/installation/index.html]. See the [INSTALL](INSTALL.md) file for build, installation and configuration steps. + +## Usage + +The [Performance Co-Pilot Quick Guides] +[https://pcp.readthedocs.io/en/latest/QG/QuickGuides.html] +provide information on how to perform basic tasks with +Performance Co-Pilot. Check the [Performance Co-Pilot +documentation][https://pcp.io/documentation.html] for addition +information about +[man pages][https://man7.org/linux/man-pages/dir_by_project.html#PCP] +and [guides][https://pcp.readthedocs.io/en/latest/]. + +## Development + For more information and details on how to contribute to the PCP project -visit [pcp.io](https://pcp.io/community.html) +visit [pcp.io](https://pcp.io/community.html). From 821e888bac61a1878304dd52953c0ae2ed2ab953 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Wed, 29 Apr 2026 16:31:56 -0400 Subject: [PATCH 4/6] Add a github Pull Request Checklist --- .github/PULL_REQUEST_TEMPLATE.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..945f25553b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +## Pull Request Description + +## Related Issues +Fixes # + +## Checklist +- [ ] ** Description ** +_Why_ this PR exists. Reference all relevant information, including _background_, _issues_, _test failures_, etc +- [ ] ** Commmits ** +_Commits_ are self contained and only do one thing +_Commits_ have a header of the form: `module: short description` +_Commits_ have a body (whenever relevant) containing a detailed description of the addressed problem and its solution +- [ ] Documentation updated +- [ ] Tests added/updated From 96caa4f38e61987f71a2419c8a54f88143d5dcc3 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Wed, 29 Apr 2026 16:33:46 -0400 Subject: [PATCH 5/6] Add templates for filing issues and feature requests on github Some times people forget to include details when filing issues on github. The template should encourage people to include additional pieces of information that would be useful in addressing the issues. --- .github/ISSUE_TEMPLATE/pcp_bug_report.yml | 61 +++++++++++++++++++ .../ISSUE_TEMPLATE/pcp_feature_request.yml | 23 +++++++ 2 files changed, 84 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/pcp_bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/pcp_feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/pcp_bug_report.yml b/.github/ISSUE_TEMPLATE/pcp_bug_report.yml new file mode 100644 index 0000000000..39f723c80b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/pcp_bug_report.yml @@ -0,0 +1,61 @@ +name: Performance Co-Pilot Issue Report +description: Create a report for a PCP related bug +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: Thank you for taking the time to fill out this bug report! + - type: textarea + id: issue-description + attributes: + label: Issue Description + description: What is the issue that you are encountering? + validations: + required: True + - type: input + id: operating-system + attributes: + label: Operating System + description: What is your machines operating system? Include name and version number.
(`cat /etc/os-release | grep -E "^(NAME=|VERSION=)"`) + placeholder: e.g. Rocky Linux Version 9.5 + validations: + required: True + - type: input + id: architecture + attributes: + label: Architecture + description: What is your machines architecture?
(`uname -m`) + placeholder: e.g. x86_64 + validations: + required: True + - type: input + id: pcp-version + attributes: + label: PCP Version + description: What version of PCP are you using (optional)?
(`(cd path_to_your_pcp_install/bin && ./pcp)`) + placeholder: e.g. main or PCP 7.1.2 + validations: + required: False + - type: input + id: component + attributes: + label: Component + description: What PCP component does this issue pertain to (optional)? + placeholder: e.g. pmlogger + validations: + required: False + - type: textarea + id: steps-to-reproduce + attributes: + label: Steps to Reproduce + description: Provide steps to reproduce this issue (optional). + validations: + required: False + - type: textarea + id: additional-information + attributes: + label: Additional Information + description: Is there any additional information that is relevant to your issue? Are there known machine configurations or versions of PCP where this issue does not occur? + validations: + required: False diff --git a/.github/ISSUE_TEMPLATE/pcp_feature_request.yml b/.github/ISSUE_TEMPLATE/pcp_feature_request.yml new file mode 100644 index 0000000000..18c92a2ced --- /dev/null +++ b/.github/ISSUE_TEMPLATE/pcp_feature_request.yml @@ -0,0 +1,23 @@ +name: Performance Co-Pilot Feature Request +description: Request additional functionality or suggest a new approach to existing functionality +title: "[RFE] " +labels: ["feature"] +body: + - type: markdown + attributes: + value: Thank you for taking the time to make a feature request! + - type: textarea + id: feature-request + attributes: + label: Description of Request for Enhancement + description: Describe the feature that you would like to see in PCP. + validations: + required: True + - type: input + id: component + attributes: + label: Component + description: If this is for a specific PCP component, please mention it here (optional). + placeholder: e.g. pmlogger + validations: + required: False From 3d78a4881f38bd4cd1833c3aef9288c06c0e836c Mon Sep 17 00:00:00 2001 From: William Cohen Date: Wed, 6 May 2026 10:48:56 -0400 Subject: [PATCH 6/6] docs: Rename CLAUDE.md files to AGENTS.md to make the them AI agent agnostic --- AGENTS.md | 194 ++++++++++++++++++++++++++++++++++++ CLAUDE.md | 195 +------------------------------------ build/mac/AGENTS.md | 114 ++++++++++++++++++++++ build/mac/CLAUDE.md | 115 +--------------------- dev/darwin/AGENTS.md | 40 ++++++++ dev/darwin/CLAUDE.md | 41 +------- src/pmdas/darwin/AGENTS.md | 149 ++++++++++++++++++++++++++++ src/pmdas/darwin/CLAUDE.md | 150 +--------------------------- src/pmrep/AGENTS.md | 166 +++++++++++++++++++++++++++++++ src/pmrep/CLAUDE.md | 167 +------------------------------ 10 files changed, 668 insertions(+), 663 deletions(-) create mode 100644 AGENTS.md create mode 100644 build/mac/AGENTS.md create mode 100644 dev/darwin/AGENTS.md create mode 100644 src/pmdas/darwin/AGENTS.md create mode 100644 src/pmrep/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..c4054d4d96 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,194 @@ +# AGENTS.md + +This file provides guidance to AI Agents (for example claude.ai/code) when working with code in this repository. + +## Project Overview + +Performance Co-Pilot (PCP) is a mature, extensible, cross-platform toolkit for system-level performance monitoring and management. It provides a unifying abstraction for all performance data in a system and many tools for interrogating, retrieving and processing that data. + +## Development Commands + +### Building and Packaging +```bash +# Configure and build from source (requires autotools) +./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc --localstatedir=/var +make + +# Build packages for the current platform +./Makepkgs --verbose + +# Cross-compile for Windows (requires MinGW) +./Makepkgs --verbose --target mingw64 + +# Install manually after building +sudo make install +``` + +### Quality Assurance Testing +```bash +# Run QA setup validation +qa/admin/check-vm + +# Install dependencies for your platform +qa/admin/list-packages -m + +# Run all QA tests +cd qa && ./check + +# Run specific tests +cd qa && ./check 000 # Run test 000 +cd qa && ./check 100-200 # Run tests 100-200 +cd qa && ./check -g pmcd # Run pmcd group tests + +# Create new test +cd qa && ./new + +# Remake expected output for a test +cd qa && ./remake 123 +``` + +### PMCD Service Management +```bash +# Start the PCP daemon +sudo systemctl start pmcd +# or +sudo service pmcd start + +# Check PCP metrics +pminfo -dfmt +pmprobe -v +``` + +## High-Level Architecture + +### Core Components + +- **libpcp**: Main PCP library providing core functionality +- **pmcd**: Performance Metrics Collection Daemon - central coordinator +- **pmlogger**: Performance data logging daemon +- **pmie**: Performance Metrics Inference Engine - rule-based monitoring +- **pmproxy**: Web API proxy and time series interface + +### Tool Categories + +1. **Data Collection Tools**: pmcd, pmlogger, various pmdas +2. **Data Export Tools**: pcp2arrow, pcp2elasticsearch, pcp2json, etc. +3. **Analysis Tools**: pminfo, pmval, pmstat, pmchart, pmrep and pcp subtools +4. **Archive Tools**: pmlogdump, pmlogextract, pmlogrewrite, pmlogsummary +5. **Administrative Tools**: pmconfig, pmlc, pmafm, pmcheck + +### PMDAs (Performance Metrics Domain Agents) + +PMDAs collect metrics from specific subsystems. Key directories in `src/pmdas/`: + +- **Platform PMDAs**: linux, darwin, aix, windows - core system metrics +- **Application PMDAs**: apache, mysql, postgres, mongodb, elasticsearch +- **System PMDAs**: bpf, bpftrace, nvidia, amdgpu +- **Network PMDAs**: cisco, bind2, apache, nginx +- **Storage PMDAs**: dm, nfsclient, gluster, xfs +- **Development PMDAs**: sample, simple, trivial - for testing and examples + +### Library Structure + +- **libpcp**: Core library with platform abstractions +- **libpcp_pmda**: PMDA development framework +- **libpcp_pmcd**: PMCD-specific functionality +- **libpcp_gui**: GUI toolkit integration +- **libpcp_web**: Web API and time series support +- **libpcp_trace**: Event trace instrumentation +- **libpcp_import**: Data import for PCP archives + +## Available Agents + +- `pcp-code-reviewer` - Reviews code against PCP project standards (whitespace, naming, structure, PCP patterns) + +## Development Guidelines + +### QA Testing Philosophy +- All changes should include appropriate QA tests +- Tests should be deterministic and portable across platforms +- Use existing archives and filtering functions where possible +- Tests run as non-root user with sudo for privileged operations + +### PMDA Development +- Use `src/pmdas/simple` or `src/pmdas/sample` as starting templates +- Follow the Install/Remove script patterns in existing PMDAs +- PMDAs can be written in C, Python, or Perl + +### Code Conventions +- Follow existing code style in surrounding files +- Add permanent diagnostics using pmDebugOptions framework +- Use GPL-compatible licensing for all contributions +- Never introduce code that logs or exposes secrets + +## Testing Requirements + +### Prerequisites +- PCP must be installed (not run from source tree) +- User "pcp" must exist for services +- User "pcpqa" used for testing via pcp-testsuite package +- Sudo access required for privileged operations + +### Essential QA Commands +```bash +# First-time setup validation +cd qa && ./check 000 + +# Check specific functionality +cd qa && ./check -g pmcd # PMCD tests +cd qa && ./check -g pmda # PMDA tests +cd qa && ./check -g archive # Archive tests +``` + +### Platform Support +PCP supports Linux, macOS, Windows (MinGW), AIX, and Solaris. Tests should be written to be portable or use `_notrun()` for platform-specific limitations. + +## macOS Development (Darwin Platform Only) + +When developing on macOS (`Platform: darwin` in environment): + +### Critical Constraints + +1. **Stage changes before VM tests** + - The Tart VM accesses the filesystem directly — `git add` is the minimum required + - Unstaged changes in `src/pmdas/darwin*` AND `build/mac/` are INVISIBLE to the VM + - A full commit also works; either way, run `/macos-qa-test` after staging + +2. **Test environments** + - Unit tests: Run locally (no PCP needed) + - Integration tests: Tart VM only (`/macos-qa-test`) + +### macOS-Specific Agent + +- `macos-darwin-pmda-qa` - Runs integration tests in isolated Tart VM + +### Quick Start +```bash +./Makepkgs --verbose # One-time: full build (5-30 min) +cd build/mac/test && ./run-all-tests.sh # Daily: build + test (20-30s) +``` + +### Key Directories + +| Directory | Purpose | +|-----------|---------| +| `build/mac/` | Test orchestration, PKG packaging, Tart VMs | +| `dev/darwin/` | Quick-compile tools (~10s vs 30min) | +| `src/pmdas/darwin/` | Darwin PMDA source code | +| `src/pmdas/darwin_proc/` | Darwin process PMDA source | + +### Documentation + +- `build/mac/CLAUDE.md` - Development workflow, test commands +- `build/mac/MACOS_DEVELOPMENT.md` - Tart VM clean-room builds + +## Nix Development + +Nix packaging is provided via `flake.nix` and the `build/nix/` directory. +See `docs/HowTos/nix/index.rst` for full documentation. + +```bash +nix build # Build PCP package +nix develop # Development shell +nix flake show # List all packages and apps +``` diff --git a/CLAUDE.md b/CLAUDE.md index 9b4c9c1da6..43c994c2d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,194 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Performance Co-Pilot (PCP) is a mature, extensible, cross-platform toolkit for system-level performance monitoring and management. It provides a unifying abstraction for all performance data in a system and many tools for interrogating, retrieving and processing that data. - -## Development Commands - -### Building and Packaging -```bash -# Configure and build from source (requires autotools) -./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc --localstatedir=/var -make - -# Build packages for the current platform -./Makepkgs --verbose - -# Cross-compile for Windows (requires MinGW) -./Makepkgs --verbose --target mingw64 - -# Install manually after building -sudo make install -``` - -### Quality Assurance Testing -```bash -# Run QA setup validation -qa/admin/check-vm - -# Install dependencies for your platform -qa/admin/list-packages -m - -# Run all QA tests -cd qa && ./check - -# Run specific tests -cd qa && ./check 000 # Run test 000 -cd qa && ./check 100-200 # Run tests 100-200 -cd qa && ./check -g pmcd # Run pmcd group tests - -# Create new test -cd qa && ./new - -# Remake expected output for a test -cd qa && ./remake 123 -``` - -### PMCD Service Management -```bash -# Start the PCP daemon -sudo systemctl start pmcd -# or -sudo service pmcd start - -# Check PCP metrics -pminfo -dfmt -pmprobe -v -``` - -## High-Level Architecture - -### Core Components - -- **libpcp**: Main PCP library providing core functionality -- **pmcd**: Performance Metrics Collection Daemon - central coordinator -- **pmlogger**: Performance data logging daemon -- **pmie**: Performance Metrics Inference Engine - rule-based monitoring -- **pmproxy**: Web API proxy and time series interface - -### Tool Categories - -1. **Data Collection Tools**: pmcd, pmlogger, various pmdas -2. **Data Export Tools**: pcp2arrow, pcp2elasticsearch, pcp2json, etc. -3. **Analysis Tools**: pminfo, pmval, pmstat, pmchart, pmrep and pcp subtools -4. **Archive Tools**: pmlogdump, pmlogextract, pmlogrewrite, pmlogsummary -5. **Administrative Tools**: pmconfig, pmlc, pmafm, pmcheck - -### PMDAs (Performance Metrics Domain Agents) - -PMDAs collect metrics from specific subsystems. Key directories in `src/pmdas/`: - -- **Platform PMDAs**: linux, darwin, aix, windows - core system metrics -- **Application PMDAs**: apache, mysql, postgres, mongodb, elasticsearch -- **System PMDAs**: bpf, bpftrace, nvidia, amdgpu -- **Network PMDAs**: cisco, bind2, apache, nginx -- **Storage PMDAs**: dm, nfsclient, gluster, xfs -- **Development PMDAs**: sample, simple, trivial - for testing and examples - -### Library Structure - -- **libpcp**: Core library with platform abstractions -- **libpcp_pmda**: PMDA development framework -- **libpcp_pmcd**: PMCD-specific functionality -- **libpcp_gui**: GUI toolkit integration -- **libpcp_web**: Web API and time series support -- **libpcp_trace**: Event trace instrumentation -- **libpcp_import**: Data import for PCP archives - -## Available Agents - -- `pcp-code-reviewer` - Reviews code against PCP project standards (whitespace, naming, structure, PCP patterns) - -## Development Guidelines - -### QA Testing Philosophy -- All changes should include appropriate QA tests -- Tests should be deterministic and portable across platforms -- Use existing archives and filtering functions where possible -- Tests run as non-root user with sudo for privileged operations - -### PMDA Development -- Use `src/pmdas/simple` or `src/pmdas/sample` as starting templates -- Follow the Install/Remove script patterns in existing PMDAs -- PMDAs can be written in C, Python, or Perl - -### Code Conventions -- Follow existing code style in surrounding files -- Add permanent diagnostics using pmDebugOptions framework -- Use GPL-compatible licensing for all contributions -- Never introduce code that logs or exposes secrets - -## Testing Requirements - -### Prerequisites -- PCP must be installed (not run from source tree) -- User "pcp" must exist for services -- User "pcpqa" used for testing via pcp-testsuite package -- Sudo access required for privileged operations - -### Essential QA Commands -```bash -# First-time setup validation -cd qa && ./check 000 - -# Check specific functionality -cd qa && ./check -g pmcd # PMCD tests -cd qa && ./check -g pmda # PMDA tests -cd qa && ./check -g archive # Archive tests -``` - -### Platform Support -PCP supports Linux, macOS, Windows (MinGW), AIX, and Solaris. Tests should be written to be portable or use `_notrun()` for platform-specific limitations. - -## macOS Development (Darwin Platform Only) - -When developing on macOS (`Platform: darwin` in environment): - -### Critical Constraints - -1. **Stage changes before VM tests** - - The Tart VM accesses the filesystem directly — `git add` is the minimum required - - Unstaged changes in `src/pmdas/darwin*` AND `build/mac/` are INVISIBLE to the VM - - A full commit also works; either way, run `/macos-qa-test` after staging - -2. **Test environments** - - Unit tests: Run locally (no PCP needed) - - Integration tests: Tart VM only (`/macos-qa-test`) - -### macOS-Specific Agent - -- `macos-darwin-pmda-qa` - Runs integration tests in isolated Tart VM - -### Quick Start -```bash -./Makepkgs --verbose # One-time: full build (5-30 min) -cd build/mac/test && ./run-all-tests.sh # Daily: build + test (20-30s) -``` - -### Key Directories - -| Directory | Purpose | -|-----------|---------| -| `build/mac/` | Test orchestration, PKG packaging, Tart VMs | -| `dev/darwin/` | Quick-compile tools (~10s vs 30min) | -| `src/pmdas/darwin/` | Darwin PMDA source code | -| `src/pmdas/darwin_proc/` | Darwin process PMDA source | - -### Documentation - -- `build/mac/CLAUDE.md` - Development workflow, test commands -- `build/mac/MACOS_DEVELOPMENT.md` - Tart VM clean-room builds - -## Nix Development - -Nix packaging is provided via `flake.nix` and the `build/nix/` directory. -See `docs/HowTos/nix/index.rst` for full documentation. - -```bash -nix build # Build PCP package -nix develop # Development shell -nix flake show # List all packages and apps -``` +@AGENTS.md diff --git a/build/mac/AGENTS.md b/build/mac/AGENTS.md new file mode 100644 index 0000000000..ea91a88574 --- /dev/null +++ b/build/mac/AGENTS.md @@ -0,0 +1,114 @@ +# Darwin PMDA Development & Testing + +Fast iteration tools for Darwin PMDA development on macOS. + +## ⚠️ macOS Development Constraints + +1. **PCP is NOT installed locally** - Don't run `pminfo`/`pmval`/`pmprobe`. Read `src/pmdas/darwin/pmns` instead. +2. **Commit before VM tests** - Tart VM only sees committed git changes. +3. **Unit tests = local, Integration tests = VM only** + +### Git Commit Requirement + +**ALL changes MUST be committed to git BEFORE running Tart VM tests.** + +This includes: +- Source code changes (`src/pmdas/darwin*`) +- Build/test scripts in THIS directory (`build/mac/`) +- Installation scripts, test fixtures, etc. + +The Tart VM clones the git repository - uncommitted local changes are invisible to it. + +--- + +## Prerequisites (One-Time Setup) + +PCP must be fully built before using quick builds: + +```bash +cd +./Makepkgs --verbose +``` + +This takes 5-30 minutes and only needs to be done once. It generates headers, builds libraries, and installs PCP. + +### Python Build Environment + +PCP's Python PMDAs (openmetrics, opentelemetry) require Python packages that aren't available system-wide on modern macOS. Install them using `uv` (which bypasses Homebrew's `externally-managed-environment` restriction): + +```bash +brew install uv # One-time: install uv package manager +./build/mac/setup-python-env.sh # Installs Python deps to system python +``` + +Run this before `./Makepkgs` or `./configure` so that `import requests` succeeds during configure checks. + +**Verify setup:** +```bash +cd dev/darwin +make check-deps +``` + +## Quick Development Workflow + +### Build + Test (Recommended) +```bash +cd build/mac/test +./run-all-tests.sh +``` + +Builds PMDA (~5-10s) and runs unit tests (~10-20s). Runs integration tests if pmcd is available. + +### Build Only +```bash +cd dev/darwin +make clean && make +``` + +### Test Only + +**Unit tests** (no installation needed): +```bash +# Darwin PMDA +cd src/pmdas/darwin/test +./run-unit-tests.sh + +# Darwin_proc PMDA +cd src/pmdas/darwin_proc/test +./run-unit-tests.sh + +# Both PMDAs +cd build/mac/test +./run-unit-tests.sh +``` + +**Integration tests** (Tart VM only - do NOT run locally): + +Integration tests require PCP installed and pmcd running. The Tart VM provides this environment. + +**Before running:** +1. Commit all changes to git (source code AND build/mac scripts) +2. Use `/macos-qa-test` skill or `macos-darwin-pmda-qa` agent + +The VM clones the git repo, so uncommitted changes are invisible + +### Centralized Test Orchestration +Quick test runners available in `build/mac/test/`: +- `./run-all-tests.sh` - Build + all unit tests + integration tests (20-30 seconds) +- `./run-unit-tests.sh` - Unit tests only for both PMDAs (no build) +- `./run-integration-tests.sh` - Integration tests only (no build) + +## Adding New Metrics + +1. Edit source: `src/pmdas/darwin/pmda.c` +2. Update PMNS: `src/pmdas/darwin/pmns` +3. Quick build: `cd dev/darwin && make` +4. Add test: `src/pmdas/darwin/test/test-.txt` +5. Run tests: `cd build/mac/test && ./run-all-tests.sh` + +## Detailed Documentation + +For in-depth procedures and troubleshooting: +- `MACOS_DEVELOPMENT.md` - Tart VM setup for clean-room builds +- `qa/TESTING.md` - pmcd launchctl test plan + diff --git a/build/mac/CLAUDE.md b/build/mac/CLAUDE.md index ea91a88574..43c994c2d3 100644 --- a/build/mac/CLAUDE.md +++ b/build/mac/CLAUDE.md @@ -1,114 +1 @@ -# Darwin PMDA Development & Testing - -Fast iteration tools for Darwin PMDA development on macOS. - -## ⚠️ macOS Development Constraints - -1. **PCP is NOT installed locally** - Don't run `pminfo`/`pmval`/`pmprobe`. Read `src/pmdas/darwin/pmns` instead. -2. **Commit before VM tests** - Tart VM only sees committed git changes. -3. **Unit tests = local, Integration tests = VM only** - -### Git Commit Requirement - -**ALL changes MUST be committed to git BEFORE running Tart VM tests.** - -This includes: -- Source code changes (`src/pmdas/darwin*`) -- Build/test scripts in THIS directory (`build/mac/`) -- Installation scripts, test fixtures, etc. - -The Tart VM clones the git repository - uncommitted local changes are invisible to it. - ---- - -## Prerequisites (One-Time Setup) - -PCP must be fully built before using quick builds: - -```bash -cd -./Makepkgs --verbose -``` - -This takes 5-30 minutes and only needs to be done once. It generates headers, builds libraries, and installs PCP. - -### Python Build Environment - -PCP's Python PMDAs (openmetrics, opentelemetry) require Python packages that aren't available system-wide on modern macOS. Install them using `uv` (which bypasses Homebrew's `externally-managed-environment` restriction): - -```bash -brew install uv # One-time: install uv package manager -./build/mac/setup-python-env.sh # Installs Python deps to system python -``` - -Run this before `./Makepkgs` or `./configure` so that `import requests` succeeds during configure checks. - -**Verify setup:** -```bash -cd dev/darwin -make check-deps -``` - -## Quick Development Workflow - -### Build + Test (Recommended) -```bash -cd build/mac/test -./run-all-tests.sh -``` - -Builds PMDA (~5-10s) and runs unit tests (~10-20s). Runs integration tests if pmcd is available. - -### Build Only -```bash -cd dev/darwin -make clean && make -``` - -### Test Only - -**Unit tests** (no installation needed): -```bash -# Darwin PMDA -cd src/pmdas/darwin/test -./run-unit-tests.sh - -# Darwin_proc PMDA -cd src/pmdas/darwin_proc/test -./run-unit-tests.sh - -# Both PMDAs -cd build/mac/test -./run-unit-tests.sh -``` - -**Integration tests** (Tart VM only - do NOT run locally): - -Integration tests require PCP installed and pmcd running. The Tart VM provides this environment. - -**Before running:** -1. Commit all changes to git (source code AND build/mac scripts) -2. Use `/macos-qa-test` skill or `macos-darwin-pmda-qa` agent - -The VM clones the git repo, so uncommitted changes are invisible - -### Centralized Test Orchestration -Quick test runners available in `build/mac/test/`: -- `./run-all-tests.sh` - Build + all unit tests + integration tests (20-30 seconds) -- `./run-unit-tests.sh` - Unit tests only for both PMDAs (no build) -- `./run-integration-tests.sh` - Integration tests only (no build) - -## Adding New Metrics - -1. Edit source: `src/pmdas/darwin/pmda.c` -2. Update PMNS: `src/pmdas/darwin/pmns` -3. Quick build: `cd dev/darwin && make` -4. Add test: `src/pmdas/darwin/test/test-.txt` -5. Run tests: `cd build/mac/test && ./run-all-tests.sh` - -## Detailed Documentation - -For in-depth procedures and troubleshooting: -- `MACOS_DEVELOPMENT.md` - Tart VM setup for clean-room builds -- `qa/TESTING.md` - pmcd launchctl test plan - +@AGENTS.md diff --git a/dev/darwin/AGENTS.md b/dev/darwin/AGENTS.md new file mode 100644 index 0000000000..fe9b281687 --- /dev/null +++ b/dev/darwin/AGENTS.md @@ -0,0 +1,40 @@ +# Darwin PMDA Quick Build Tools + +This directory provides fast iteration for Darwin PMDA development (~10 second compile vs 30 minute full build). + +It "cheats" by generating a minimal GNUmakefile that links against pre-built libraries from a complete Makepkgs run. + +## Prerequisites + +1. Run full build once (generates headers/libs): + ```bash + cd && ./Makepkgs --verbose + ``` + +2. Initialize the quick-build environment: + ```bash + ./setup-local-pcp.sh + ``` + +## Quick Commands + +| Command | Purpose | +|---------|---------| +| `make clean && make` | Compile PMDA (~5-10s) | +| `./build-quick.sh` | Compile + smoke test | +| `./dev-test.sh` | Compile + PMDA tests | + +## Recommended Workflow + +Use the centralized test runner instead of these individual scripts: +```bash +cd /build/mac/test && ./run-all-tests.sh +``` + +## Source Location + +**Edit source in** `src/pmdas/darwin/` - this directory only compiles it. + +## See Also + +- [macOS Build & Test Hub](../../build/mac/CLAUDE.md) diff --git a/dev/darwin/CLAUDE.md b/dev/darwin/CLAUDE.md index fe9b281687..43c994c2d3 100644 --- a/dev/darwin/CLAUDE.md +++ b/dev/darwin/CLAUDE.md @@ -1,40 +1 @@ -# Darwin PMDA Quick Build Tools - -This directory provides fast iteration for Darwin PMDA development (~10 second compile vs 30 minute full build). - -It "cheats" by generating a minimal GNUmakefile that links against pre-built libraries from a complete Makepkgs run. - -## Prerequisites - -1. Run full build once (generates headers/libs): - ```bash - cd && ./Makepkgs --verbose - ``` - -2. Initialize the quick-build environment: - ```bash - ./setup-local-pcp.sh - ``` - -## Quick Commands - -| Command | Purpose | -|---------|---------| -| `make clean && make` | Compile PMDA (~5-10s) | -| `./build-quick.sh` | Compile + smoke test | -| `./dev-test.sh` | Compile + PMDA tests | - -## Recommended Workflow - -Use the centralized test runner instead of these individual scripts: -```bash -cd /build/mac/test && ./run-all-tests.sh -``` - -## Source Location - -**Edit source in** `src/pmdas/darwin/` - this directory only compiles it. - -## See Also - -- [macOS Build & Test Hub](../../build/mac/CLAUDE.md) +@AGENTS.md diff --git a/src/pmdas/darwin/AGENTS.md b/src/pmdas/darwin/AGENTS.md new file mode 100644 index 0000000000..c6eddafe11 --- /dev/null +++ b/src/pmdas/darwin/AGENTS.md @@ -0,0 +1,149 @@ +This directory contains the macOS(Darwin) PMDA source code, which provides native integration +for the macOS operating system. + +## CRITICAL: macOS Development Constraints + +### PCP Is NOT Installed Locally +**NEVER assume PCP tools (`pminfo`, `pmval`, `pmprobe`) are available on the development host.** + +To check available metrics or PMNS structure: +- Read `src/pmdas/darwin/pmns` directly - this is the source of truth +- Do NOT try to run PCP commands locally + +### Testing Environments + +| Test Type | Where to Run | PCP Required? | +|-----------|--------------|---------------| +| **Unit tests** | Local (`./run-unit-tests.sh`) | No | +| **Integration tests** | Tart VM only (`/macos-qa-test`) | Yes (VM has it) | + +### Git Commit Requirement + +**ALL source code changes MUST be committed to git BEFORE running integration tests.** + +The Tart VM clones the git repository - uncommitted local changes are invisible to it. + +```bash +# Correct workflow: +git add +git commit -m "description" +/macos-qa-test # Now VM can see your changes +``` + +## Code Style + +* Keep method lengths short, with the "Single Responsibility principal" in mind +* Make the method names descriptive and readable +* Keep the code-style inline with other code in this directory +* Code **MUST** be reviewed and approved by the `pcp-code-reviewer` sub-agent + +## Adding New Metrics + +### Pattern: Follow VFS Module Template +When adding new metric clusters, use `vfs.h`/`vfs.c` as the reference pattern: +- Create `.h` with typedef struct and refresh/fetch prototypes +- Create `.c` with `refresh_()` using `sysctlbyname()` calls +- Add `CLUSTER_` to `darwin.h` enum +- Wire into `pmda.c`: include header, add global vars, add to `darwin_refresh()` and `darwin_fetchCallBack()` +- Add metrics to `metrics.c`: include header, extern declaration, metric entries +- Add to `GNUmakefile` CFILES and HFILES + +### CRITICAL: Instance Domain Registration +When adding new instance domains (standard PMDA requirement): +1. Add enum entry to `darwin.h` (e.g., `FAN_INDOM`) +2. **MUST** add corresponding entry to `indomtab[]` array in `pmda.c` +3. Dynamic instance domains: `{ INDOM_NAME, 0, NULL }` (populated at runtime) +4. Missing indomtab entry causes: "Undefined instance domain serial (N)" - entire PMDA fails to load + +### Instance Domain Update Pattern +Standard PMDA pattern (see `disk.c:update_disk_indom()` or Linux PMDA `proc_buddyinfo.c`): +```c +indom->it_set = realloc(indom->it_set, count * sizeof(pmdaInstid)); +indom->it_numinst = count; +``` +No helper function exists - directly manipulate `it_set` and `it_numinst`. + +### CRITICAL: PMNS Root Namespace +When adding new top-level metric namespaces: +1. Define metrics in `pmns` file (e.g., `ipc { ... }`) +2. **MUST** add namespace to `root` file's root block (e.g., add `ipc` to root list) +3. Failure to update `root` causes "Disconnected subtree" PMNS parsing errors during build + +**Example:** +```diff +root { + kernel + ... ++ ipc +} +``` + +## SMC (System Management Controller) Access + +The Darwin PMDA includes thermal monitoring via Apple's SMC (System Management Controller), +which provides access to temperature sensors and fan metrics. + +### Important: Reverse-Engineered APIs + +SMC access is **community reverse-engineered** and **NOT officially supported by Apple**. +The APIs may change between macOS versions and may require entitlements on newer systems. + +### Reference Documentation + +- **iSMC** (https://github.com/dkorunic/iSMC) - CLI tool with Apple Silicon support + - Reference for SMC key patterns on M1/M2/M3 Macs + - Demonstrates sp78 and fpe2 format conversions + +- **SMCKit** (https://github.com/beltex/SMCKit) - Comprehensive Swift library + - Extensive SMC key documentation for Intel and Apple Silicon + - Reference for fan control and thermal sensor keys + +### SMC Key Formats + +| Format | Type | Conversion | Usage | +|--------|------|------------|-------| +| sp78 | Signed fixed-point | ÷256 | Temperature (°C) | +| fpe2 | Unsigned fixed-point | ÷4 | Fan RPM | +| ui8 | Unsigned 8-bit | Direct | Fan count, flags | + +### Key Patterns by Platform + +**Apple Silicon (M1/M2/M3):** +- Temperature: `Tp01` (CPU die), `Tg01` (GPU die), `TCXC` (package) +- Fan: `FNum` (count), `F0Ac`/`F1Ac` (speed), `F0Tg`/`F1Tg` (target) + +**Intel Macs:** +- Temperature: `TC0P` (CPU proximity), `TG0D` (GPU die) +- Fan patterns same as Apple Silicon + +### Graceful Degradation + +The thermal subsystem degrades gracefully when SMC access fails: +- Thermal pressure metrics always work (notify API, no SMC required) +- Temperature/fan metrics return `PM_ERR_APPVERSION` if SMC unavailable +- Fanless Macs (MacBook Air) report `hinv.nfan=0` correctly + +## Testing & QA + +### Unit Tests (Run Locally) +Unit tests do NOT require PCP installation: +```bash +cd src/pmdas/darwin/test && ./run-unit-tests.sh +``` + +### Integration Tests (Tart VM Only) +Integration tests MUST run in the isolated Tart VM environment. Use the `macos-darwin-pmda-qa` agent or invoke `/macos-qa-test`: + +**Before running:** +1. Commit all source changes to git +2. Then run: `/macos-qa-test` + +The agent handles `cirrus run --dirty` and reports results. + +### Code Review +Use the `pcp-code-reviewer` agent to review changes against PCP project standards + +## Related code areas +* .github/workflows/macOS.yml - macOS-specific Github action which builds, packages and runs the unit tests. ANy changes in the Darwin PMDA will impact this. Consider any impact a change might have on this workflow file. +* .cirrus.yml - local CI runner, acts similar to the macOS Github runner mentioned previously. Also analyse any changes for impacts on this local runner too. + diff --git a/src/pmdas/darwin/CLAUDE.md b/src/pmdas/darwin/CLAUDE.md index c6eddafe11..43c994c2d3 100644 --- a/src/pmdas/darwin/CLAUDE.md +++ b/src/pmdas/darwin/CLAUDE.md @@ -1,149 +1 @@ -This directory contains the macOS(Darwin) PMDA source code, which provides native integration -for the macOS operating system. - -## CRITICAL: macOS Development Constraints - -### PCP Is NOT Installed Locally -**NEVER assume PCP tools (`pminfo`, `pmval`, `pmprobe`) are available on the development host.** - -To check available metrics or PMNS structure: -- Read `src/pmdas/darwin/pmns` directly - this is the source of truth -- Do NOT try to run PCP commands locally - -### Testing Environments - -| Test Type | Where to Run | PCP Required? | -|-----------|--------------|---------------| -| **Unit tests** | Local (`./run-unit-tests.sh`) | No | -| **Integration tests** | Tart VM only (`/macos-qa-test`) | Yes (VM has it) | - -### Git Commit Requirement - -**ALL source code changes MUST be committed to git BEFORE running integration tests.** - -The Tart VM clones the git repository - uncommitted local changes are invisible to it. - -```bash -# Correct workflow: -git add -git commit -m "description" -/macos-qa-test # Now VM can see your changes -``` - -## Code Style - -* Keep method lengths short, with the "Single Responsibility principal" in mind -* Make the method names descriptive and readable -* Keep the code-style inline with other code in this directory -* Code **MUST** be reviewed and approved by the `pcp-code-reviewer` sub-agent - -## Adding New Metrics - -### Pattern: Follow VFS Module Template -When adding new metric clusters, use `vfs.h`/`vfs.c` as the reference pattern: -- Create `.h` with typedef struct and refresh/fetch prototypes -- Create `.c` with `refresh_()` using `sysctlbyname()` calls -- Add `CLUSTER_` to `darwin.h` enum -- Wire into `pmda.c`: include header, add global vars, add to `darwin_refresh()` and `darwin_fetchCallBack()` -- Add metrics to `metrics.c`: include header, extern declaration, metric entries -- Add to `GNUmakefile` CFILES and HFILES - -### CRITICAL: Instance Domain Registration -When adding new instance domains (standard PMDA requirement): -1. Add enum entry to `darwin.h` (e.g., `FAN_INDOM`) -2. **MUST** add corresponding entry to `indomtab[]` array in `pmda.c` -3. Dynamic instance domains: `{ INDOM_NAME, 0, NULL }` (populated at runtime) -4. Missing indomtab entry causes: "Undefined instance domain serial (N)" - entire PMDA fails to load - -### Instance Domain Update Pattern -Standard PMDA pattern (see `disk.c:update_disk_indom()` or Linux PMDA `proc_buddyinfo.c`): -```c -indom->it_set = realloc(indom->it_set, count * sizeof(pmdaInstid)); -indom->it_numinst = count; -``` -No helper function exists - directly manipulate `it_set` and `it_numinst`. - -### CRITICAL: PMNS Root Namespace -When adding new top-level metric namespaces: -1. Define metrics in `pmns` file (e.g., `ipc { ... }`) -2. **MUST** add namespace to `root` file's root block (e.g., add `ipc` to root list) -3. Failure to update `root` causes "Disconnected subtree" PMNS parsing errors during build - -**Example:** -```diff -root { - kernel - ... -+ ipc -} -``` - -## SMC (System Management Controller) Access - -The Darwin PMDA includes thermal monitoring via Apple's SMC (System Management Controller), -which provides access to temperature sensors and fan metrics. - -### Important: Reverse-Engineered APIs - -SMC access is **community reverse-engineered** and **NOT officially supported by Apple**. -The APIs may change between macOS versions and may require entitlements on newer systems. - -### Reference Documentation - -- **iSMC** (https://github.com/dkorunic/iSMC) - CLI tool with Apple Silicon support - - Reference for SMC key patterns on M1/M2/M3 Macs - - Demonstrates sp78 and fpe2 format conversions - -- **SMCKit** (https://github.com/beltex/SMCKit) - Comprehensive Swift library - - Extensive SMC key documentation for Intel and Apple Silicon - - Reference for fan control and thermal sensor keys - -### SMC Key Formats - -| Format | Type | Conversion | Usage | -|--------|------|------------|-------| -| sp78 | Signed fixed-point | ÷256 | Temperature (°C) | -| fpe2 | Unsigned fixed-point | ÷4 | Fan RPM | -| ui8 | Unsigned 8-bit | Direct | Fan count, flags | - -### Key Patterns by Platform - -**Apple Silicon (M1/M2/M3):** -- Temperature: `Tp01` (CPU die), `Tg01` (GPU die), `TCXC` (package) -- Fan: `FNum` (count), `F0Ac`/`F1Ac` (speed), `F0Tg`/`F1Tg` (target) - -**Intel Macs:** -- Temperature: `TC0P` (CPU proximity), `TG0D` (GPU die) -- Fan patterns same as Apple Silicon - -### Graceful Degradation - -The thermal subsystem degrades gracefully when SMC access fails: -- Thermal pressure metrics always work (notify API, no SMC required) -- Temperature/fan metrics return `PM_ERR_APPVERSION` if SMC unavailable -- Fanless Macs (MacBook Air) report `hinv.nfan=0` correctly - -## Testing & QA - -### Unit Tests (Run Locally) -Unit tests do NOT require PCP installation: -```bash -cd src/pmdas/darwin/test && ./run-unit-tests.sh -``` - -### Integration Tests (Tart VM Only) -Integration tests MUST run in the isolated Tart VM environment. Use the `macos-darwin-pmda-qa` agent or invoke `/macos-qa-test`: - -**Before running:** -1. Commit all source changes to git -2. Then run: `/macos-qa-test` - -The agent handles `cirrus run --dirty` and reports results. - -### Code Review -Use the `pcp-code-reviewer` agent to review changes against PCP project standards - -## Related code areas -* .github/workflows/macOS.yml - macOS-specific Github action which builds, packages and runs the unit tests. ANy changes in the Darwin PMDA will impact this. Consider any impact a change might have on this workflow file. -* .cirrus.yml - local CI runner, acts similar to the macOS Github runner mentioned previously. Also analyse any changes for impacts on this local runner too. - +@AGENTS.md diff --git a/src/pmrep/AGENTS.md b/src/pmrep/AGENTS.md new file mode 100644 index 0000000000..c11ef070bd --- /dev/null +++ b/src/pmrep/AGENTS.md @@ -0,0 +1,166 @@ +# pmrep Configuration Development + +Guide for developing pmrep configuration files in `conf/`. + +## Critical: ConfigParser Percent Sign Escaping + +**pmrep config files are parsed by Python's ConfigParser, which treats `%` as a special interpolation character.** + +### The Rule + +Always escape percent signs in metric labels and values by doubling them: `%` → `%%` + +### Examples + +**Wrong (causes InterpolationSyntaxError):** +```ini +gpu.util = util%,,,,6 +cpu_usage.label = cpu% +``` + +**Correct:** +```ini +gpu.util = util%%,,,,6 +cpu_usage.label = cpu%% +``` + +### Common Error + +``` +configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%,,,,6' +``` + +**Fix:** Double all `%` characters that should appear literally in output. + +## Unit Specifications + +**PCP's unit conversion system only recognizes standard units. Custom units cause `PM_ERR_CONV` errors.** + +### Supported Units + +- **Storage**: KB, MB, GB, TB, PB +- **Time**: s, ms, us, ns +- **Count**: count, none (dimensionless) + +### Unsupported Units + +If the darwin PMDA defines a metric as dimensionless (`PMDA_PMUNITS(0,0,0,0,0,0)`), omit the unit specification in pmrep config: + +**Wrong (causes PM_ERR_CONV):** +```ini +power.battery.temperature = temp,,dC,,5 +power.battery.capacity.design = design,,mAh,,7 +``` + +**Correct:** +```ini +power.battery.temperature = temp,,,,5 # Raw Celsius value +power.battery.capacity.design = design,,,,7 # Raw mAh value +``` + +Use comments and labels to indicate units - don't try to convert them. + +## Configuration File Format + +pmrep configs use INI format with specific semantics: + +### Basic Metric Definition + +```ini +[view-name] +header = yes +unitinfo = no +globals = no +timestamp = no +precision = 0 +delimiter = " " +repeat_header = auto + +# Direct metric mapping +metric.name = label,,unit,,width +``` + +### Derived Metrics with Formulas + +```ini +# Derived metric (computed from other metrics) +derived_name = base.metric.name +derived_name.label = label +derived_name.formula = 100 * rate(metric.a) / hinv.ncpu +derived_name.unit = s +derived_name.width = 5 +``` + +**Note:** If your formula includes division, ensure denominators can't be zero, or accept that pmrep may show "N/A" for those samples. + +## Testing pmrep Configurations + +### Syntax Validation + +```bash +# Test that a view loads without errors +pmrep -t 1 -s 1 :view-name + +# Test with actual metrics (requires pmcd running) +pmrep -t 1 -s 3 :view-name +``` + +### Integration Testing + +pmrep configs are installed to `$(PCP_SYSCONF_DIR)/pmrep` during `make install`. Test changes in the installed location, not the source tree. + +On macOS (Darwin PMDA development): +1. Commit changes to git (VM clones the repo) +2. Run `/macos-qa-test` skill to test in isolated VM with pmcd running + +## Common Patterns + +### Percentage Calculations + +```ini +# CPU utilization percentage +usr = kernel.all.cpu.usrp +usr.label = us +usr.formula = 100 * (kernel.all.cpu.user + kernel.all.cpu.nice) / hinv.ncpu +usr.unit = s +usr.width = 3 +``` + +### Aggregation Across Instances + +```ini +# Sum across all network interfaces +net_total = network.total.bytes +net_total.label = total +net_total.formula = sum(network.interface.in.bytes) +net_total.unit = KB +net_total.width = 8 +``` + +### Rate Calculations + +```ini +# IOPS from counter metrics +iops = disk.rate +iops.formula = rate(disk.dev.total) +iops.width = 7 +``` + +## File Organization + +- `conf/*.conf` - View configurations organized by theme +- `conf/GNUmakefile` - Installs all `.conf` files to system location +- Pattern: `$(shell echo *.conf)` picks up new files automatically + +## Platform-Specific Views + +Views can reference platform-specific metrics. If a metric doesn't exist on a platform, pmrep will show "N/A" for that field rather than failing the entire view. + +Example: `macstat.conf` uses Darwin-specific metrics like `mem.util.compressed` which don't exist on Linux. + +## References + +- pmrep(1) man page - Command-line options and behavior +- Python ConfigParser docs - Understanding interpolation syntax +- `conf/pmstat.conf` - Simple, well-commented example +- `conf/collectl.conf` - Complex example with many derived metrics diff --git a/src/pmrep/CLAUDE.md b/src/pmrep/CLAUDE.md index c11ef070bd..43c994c2d3 100644 --- a/src/pmrep/CLAUDE.md +++ b/src/pmrep/CLAUDE.md @@ -1,166 +1 @@ -# pmrep Configuration Development - -Guide for developing pmrep configuration files in `conf/`. - -## Critical: ConfigParser Percent Sign Escaping - -**pmrep config files are parsed by Python's ConfigParser, which treats `%` as a special interpolation character.** - -### The Rule - -Always escape percent signs in metric labels and values by doubling them: `%` → `%%` - -### Examples - -**Wrong (causes InterpolationSyntaxError):** -```ini -gpu.util = util%,,,,6 -cpu_usage.label = cpu% -``` - -**Correct:** -```ini -gpu.util = util%%,,,,6 -cpu_usage.label = cpu%% -``` - -### Common Error - -``` -configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%,,,,6' -``` - -**Fix:** Double all `%` characters that should appear literally in output. - -## Unit Specifications - -**PCP's unit conversion system only recognizes standard units. Custom units cause `PM_ERR_CONV` errors.** - -### Supported Units - -- **Storage**: KB, MB, GB, TB, PB -- **Time**: s, ms, us, ns -- **Count**: count, none (dimensionless) - -### Unsupported Units - -If the darwin PMDA defines a metric as dimensionless (`PMDA_PMUNITS(0,0,0,0,0,0)`), omit the unit specification in pmrep config: - -**Wrong (causes PM_ERR_CONV):** -```ini -power.battery.temperature = temp,,dC,,5 -power.battery.capacity.design = design,,mAh,,7 -``` - -**Correct:** -```ini -power.battery.temperature = temp,,,,5 # Raw Celsius value -power.battery.capacity.design = design,,,,7 # Raw mAh value -``` - -Use comments and labels to indicate units - don't try to convert them. - -## Configuration File Format - -pmrep configs use INI format with specific semantics: - -### Basic Metric Definition - -```ini -[view-name] -header = yes -unitinfo = no -globals = no -timestamp = no -precision = 0 -delimiter = " " -repeat_header = auto - -# Direct metric mapping -metric.name = label,,unit,,width -``` - -### Derived Metrics with Formulas - -```ini -# Derived metric (computed from other metrics) -derived_name = base.metric.name -derived_name.label = label -derived_name.formula = 100 * rate(metric.a) / hinv.ncpu -derived_name.unit = s -derived_name.width = 5 -``` - -**Note:** If your formula includes division, ensure denominators can't be zero, or accept that pmrep may show "N/A" for those samples. - -## Testing pmrep Configurations - -### Syntax Validation - -```bash -# Test that a view loads without errors -pmrep -t 1 -s 1 :view-name - -# Test with actual metrics (requires pmcd running) -pmrep -t 1 -s 3 :view-name -``` - -### Integration Testing - -pmrep configs are installed to `$(PCP_SYSCONF_DIR)/pmrep` during `make install`. Test changes in the installed location, not the source tree. - -On macOS (Darwin PMDA development): -1. Commit changes to git (VM clones the repo) -2. Run `/macos-qa-test` skill to test in isolated VM with pmcd running - -## Common Patterns - -### Percentage Calculations - -```ini -# CPU utilization percentage -usr = kernel.all.cpu.usrp -usr.label = us -usr.formula = 100 * (kernel.all.cpu.user + kernel.all.cpu.nice) / hinv.ncpu -usr.unit = s -usr.width = 3 -``` - -### Aggregation Across Instances - -```ini -# Sum across all network interfaces -net_total = network.total.bytes -net_total.label = total -net_total.formula = sum(network.interface.in.bytes) -net_total.unit = KB -net_total.width = 8 -``` - -### Rate Calculations - -```ini -# IOPS from counter metrics -iops = disk.rate -iops.formula = rate(disk.dev.total) -iops.width = 7 -``` - -## File Organization - -- `conf/*.conf` - View configurations organized by theme -- `conf/GNUmakefile` - Installs all `.conf` files to system location -- Pattern: `$(shell echo *.conf)` picks up new files automatically - -## Platform-Specific Views - -Views can reference platform-specific metrics. If a metric doesn't exist on a platform, pmrep will show "N/A" for that field rather than failing the entire view. - -Example: `macstat.conf` uses Darwin-specific metrics like `mem.util.compressed` which don't exist on Linux. - -## References - -- pmrep(1) man page - Command-line options and behavior -- Python ConfigParser docs - Understanding interpolation syntax -- `conf/pmstat.conf` - Simple, well-commented example -- `conf/collectl.conf` - Complex example with many derived metrics +@AGENTS.md