Manuel Ganter
addab99e5d
All checks were successful
ci / build (push) Successful in 26s
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build and Development Commands
|
|
|
|
```bash
|
|
# Build
|
|
make build # Build the collector binary
|
|
go build -o collector ./cmd/collector
|
|
go build -o receiver ./cmd/receiver
|
|
|
|
# Test
|
|
make test # Run all tests
|
|
go test -v ./... # Run all tests with verbose output
|
|
go test -v ./internal/collector/... # Run tests for a specific package
|
|
make test-coverage # Run tests with coverage report
|
|
|
|
# Code Quality
|
|
make fmt # Format code
|
|
make vet # Run go vet
|
|
make lint # Run golangci-lint (v2.6.2)
|
|
make all # Format, vet, lint, and build
|
|
|
|
# Git Hooks
|
|
make install-hooks # Install pre-commit and commit-msg hooks
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
This is a Go metrics collector designed for CI/CD environments with shared PID namespaces. It consists of two binaries:
|
|
|
|
### Collector (`cmd/collector`)
|
|
Runs alongside CI workloads, periodically reads `/proc` filesystem, and pushes a summary to the receiver on shutdown (SIGINT/SIGTERM).
|
|
|
|
**Data Flow:**
|
|
1. `metrics.Aggregator` reads `/proc` to collect CPU/memory for all processes
|
|
2. `collector.Collector` orchestrates collection at intervals and writes to output
|
|
3. `summary.Accumulator` tracks samples across the run, computing peak/avg/percentiles
|
|
4. On shutdown, `summary.PushClient` sends the summary to the receiver HTTP endpoint
|
|
|
|
### Receiver (`cmd/receiver`)
|
|
HTTP service that stores metric summaries in SQLite (via GORM) and provides a query API.
|
|
|
|
**Key Endpoints:**
|
|
- `POST /api/v1/metrics` - Receive metrics from collectors
|
|
- `GET /api/v1/metrics/repo/{org}/{repo}/{workflow}/{job}` - Query stored metrics
|
|
|
|
### Internal Packages
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `internal/collector` | Orchestrates collection loop, handles shutdown |
|
|
| `internal/metrics` | Aggregates system/process metrics from /proc |
|
|
| `internal/proc` | Low-level /proc parsing (stat, status, cgroup) |
|
|
| `internal/cgroup` | Parses CGROUP_LIMITS and CGROUP_PROCESS_MAP env vars |
|
|
| `internal/summary` | Accumulates samples, computes stats, pushes to receiver |
|
|
| `internal/receiver` | HTTP handlers and SQLite store |
|
|
| `internal/output` | Metrics output formatting (JSON/text) |
|
|
|
|
### Container Metrics
|
|
|
|
The collector groups processes by container using cgroup paths. Configuration via environment variables:
|
|
- `CGROUP_PROCESS_MAP`: JSON mapping process names to container names (e.g., `{"node":"runner"}`)
|
|
- `CGROUP_LIMITS`: JSON with CPU/memory limits per container for percentage calculations
|
|
|
|
CPU values in container metrics are reported as **cores** (not percentage), enabling direct comparison with Kubernetes resource limits.
|
|
|
|
## Commit Message Convention
|
|
|
|
Uses conventional commits enforced by git hook:
|
|
```
|
|
<type>(<scope>)?: <description>
|
|
```
|
|
|
|
Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`
|
|
|
|
Examples:
|
|
- `feat: add user authentication`
|
|
- `fix(collector): handle nil cgroup paths`
|
|
- `feat!: breaking change in API`
|
|
|
|
## Running Locally
|
|
|
|
```bash
|
|
# Run receiver
|
|
./receiver --addr=:8080 --db=metrics.db
|
|
|
|
# Run collector with push endpoint
|
|
./collector --interval=2s --top=10 --push-endpoint=http://localhost:8080/api/v1/metrics
|
|
|
|
# Docker Compose stress test
|
|
docker compose -f test/docker/docker-compose-stress.yaml up -d
|
|
```
|