Skip to content

CLAUDE.md

Latest commit

 

History

History
194 lines (142 loc) · 5.97 KB

CLAUDE.md

File metadata and controls

194 lines (142 loc) · 5.97 KB

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

# 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

# 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

# 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

# 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

./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.

nix build              # Build PCP package
nix develop            # Development shell
nix flake show         # List all packages and apps