|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to AI coding agents when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Cortex is a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus metrics. It uses a microservices architecture with components that can run as separate processes or as a single binary. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +make # Build all (runs in Docker container by default) |
| 13 | +make BUILD_IN_CONTAINER=false # Build locally without Docker |
| 14 | +make exes # Build binaries only |
| 15 | +make protos # Generate protobuf files |
| 16 | +make lint # Run all linters (golangci-lint, misspell, etc.) |
| 17 | +make doc # Generate config documentation (run after changing flags/config) |
| 18 | +make ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests |
| 19 | +``` |
| 20 | + |
| 21 | +## Testing |
| 22 | + |
| 23 | +### Unit Tests |
| 24 | + |
| 25 | +```bash |
| 26 | +go test -timeout 2400s -tags "netgo slicelabels" ./... # Run tests with CI configuration |
| 27 | +``` |
| 28 | + |
| 29 | +### Integration Tests |
| 30 | + |
| 31 | +Integration tests require Docker and the Cortex image to be built first: |
| 32 | + |
| 33 | +```bash |
| 34 | +make ./cmd/cortex/.uptodate # Build Cortex Docker image first |
| 35 | + |
| 36 | +# Run all integration tests |
| 37 | +go test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/... |
| 38 | + |
| 39 | +# Run a specific integration test |
| 40 | +go test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run "^TestRulerAPISharding$" |
| 41 | +``` |
| 42 | + |
| 43 | +Environment variables for integration tests: |
| 44 | + |
| 45 | +- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`) |
| 46 | +- `E2E_TEMP_DIR` - Directory for temporary test files |
| 47 | + |
| 48 | +## Code Formatting |
| 49 | + |
| 50 | +Use goimports with Cortex-specific import grouping: |
| 51 | + |
| 52 | +```bash |
| 53 | +goimports -local github.com/cortexproject/cortex -w ./path/to/file.go |
| 54 | +``` |
| 55 | + |
| 56 | +Import order: stdlib, third-party packages, internal Cortex packages (separated by blank lines). |
| 57 | + |
| 58 | +## Architecture |
| 59 | + |
| 60 | +### Write Path |
| 61 | + |
| 62 | +- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing |
| 63 | +- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks) |
| 64 | + |
| 65 | +### Read Path |
| 66 | + |
| 67 | +- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage |
| 68 | +- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing |
| 69 | +- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling |
| 70 | + |
| 71 | +### Storage |
| 72 | + |
| 73 | +- **Compactor** (stateless) - Compacts TSDB blocks in object storage |
| 74 | +- **Store Gateway** (semi-stateful) - Queries blocks from object storage |
| 75 | + |
| 76 | +### Optional Services |
| 77 | + |
| 78 | +- **Ruler** - Executes recording rules and alerts |
| 79 | +- **Alertmanager** - Multi-tenant alert routing |
| 80 | +- **Configs API** - Configuration management |
| 81 | + |
| 82 | +### Key Patterns |
| 83 | + |
| 84 | +- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution |
| 85 | +- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header |
| 86 | +- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift |
| 87 | + |
| 88 | +### Main Entry Points |
| 89 | + |
| 90 | +- `cmd/cortex/main.go` - Main Cortex binary |
| 91 | +- `pkg/cortex/cortex.go` - Service orchestration and configuration |
| 92 | + |
| 93 | +## Code Conventions |
| 94 | + |
| 95 | +- **No global variables** - Use dependency injection |
| 96 | +- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer |
| 97 | +- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case` |
| 98 | +- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`) |
| 99 | + |
| 100 | +## PR Requirements |
| 101 | + |
| 102 | +- Sign commits with DCO: `git commit -s -m "message"` |
| 103 | +- Run `make doc` if config/flags changed |
| 104 | +- Include CHANGELOG entry for user-facing changes |
0 commit comments