{"owner":"cortexproject","repo":"cortex","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex 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.\n\n## Build Commands\n\n```bash\nmake                           # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false  # Build locally without Docker\nmake exes                      # Build binaries only\nmake protos                    # Generate protobuf files\nmake lint                      # Run all linters (golangci-lint, misspell, etc.)\nmake doc                       # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version  # Update go.mod\ngo mod vendor                               # Sync vendor folder\ngo mod tidy                                 # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./...          # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs/<run-id>/jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs/<job-id>/annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view <run-id> --job <job-id> --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n   - The full error output in a `<details>` block (since job links can expire)\n   - Root cause analysis\n   - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n   - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex 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.\n\n## Build Commands\n\n```bash\nmake                           # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false  # Build locally without Docker\nmake exes                      # Build binaries only\nmake protos                    # Generate protobuf files\nmake lint                      # Run all linters (golangci-lint, misspell, etc.)\nmake doc                       # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version  # Update go.mod\ngo mod vendor                               # Sync vendor folder\ngo mod tidy                                 # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./...          # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs/<run-id>/jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs/<job-id>/annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view <run-id> --job <job-id> --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n   - The full error output in a `<details>` block (since job links can expire)\n   - Root cause analysis\n   - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n   - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nCortex 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.\n\n## Build Commands\n\n```bash\nmake                           # Build all (runs in Docker container by default)\nmake BUILD_IN_CONTAINER=false  # Build locally without Docker\nmake exes                      # Build binaries only\nmake protos                    # Generate protobuf files\nmake lint                      # Run all linters (golangci-lint, misspell, etc.)\nmake doc                       # Generate config documentation (run after changing flags/config)\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image for integration tests\n```\n\n## Vendored Dependencies\n\nGo modules are vendored in the `vendor/` folder. When upgrading a dependency or component:\n\n```bash\ngo get github.com/some/dependency@version  # Update go.mod\ngo mod vendor                               # Sync vendor folder\ngo mod tidy                                 # Clean up go.mod/go.sum\n```\n\n**Important**: Always check the `vendor/` folder for upstream library code (e.g., `vendor/github.com/prometheus/alertmanager/` for Alertmanager internals). Do not modify vendored code directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ngo test -timeout 2400s -tags \"netgo slicelabels\" ./...          # Run tests with CI configuration\n```\n\n### Integration Tests\n\nIntegration tests require Docker and the Cortex image to be built first:\n\n```bash\nmake ./cmd/cortex/.uptodate    # Build Cortex Docker image first\n\n# Run all integration tests\ngo test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...\n\n# Run a specific integration test\ngo test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run \"^TestRulerAPISharding$\"\n```\n\nEnvironment variables for integration tests:\n\n- `CORTEX_IMAGE` - Docker image to test (default: `quay.io/cortexproject/cortex:latest`)\n- `E2E_TEMP_DIR` - Directory for temporary test files\n\n## Code Formatting\n\nUse goimports with Cortex-specific import grouping:\n\n```bash\ngoimports -local github.com/cortexproject/cortex -w ./path/to/file.go\n```\n\nImport order: stdlib, third-party packages, internal Cortex packages (separated by blank lines).\n\n## Architecture\n\n### Write Path\n\n- **Distributor** (stateless) - Receives samples via remote write, validates, distributes to ingesters using consistent hashing\n- **Ingester** (semi-stateful) - Stores samples in memory, periodically flushes to long-term storage (TSDB blocks)\n\n### Read Path\n\n- **Querier** (stateless) - Executes PromQL queries across ingesters and long-term storage\n- **Query Frontend** (optional, stateless) - Query caching, splitting, and queueing\n- **Query Scheduler** (optional, stateless) - Moves queue from frontend for independent scaling\n\n### Storage\n\n- **Compactor** (stateless) - Compacts TSDB blocks in object storage\n- **Store Gateway** (semi-stateful) - Queries blocks from object storage\n\n### Optional Services\n\n- **Ruler** - Executes recording rules and alerts\n- **Alertmanager** - Multi-tenant alert routing\n- **Configs API** - Configuration management\n\n### Key Patterns\n\n- **Hash Ring** - Consistent hashing via Consul, Etcd, or memberlist gossip for data distribution\n- **Multi-tenancy** - Tenant isolation via `X-Scope-OrgID` header\n- **Blocks Storage** - TSDB-based storage with 2-hour block ranges, stored in S3/GCS/Azure/Swift\n\n### Main Entry Points\n\n- `cmd/cortex/main.go` - Main Cortex binary\n- `pkg/cortex/cortex.go` - Service orchestration and configuration\n\n## Code Conventions\n\n- **No global variables** - Use dependency injection\n- **Metrics**: Register with `promauto.With(reg)`, never use global prometheus registerer\n- **Config naming**: YAML uses `snake_case`, CLI flags use `kebab-case`\n- **Logging**: Use `github.com/go-kit/log` (not `github.com/go-kit/kit/log`)\n\n## PR Requirements\n\n- Sign commits with DCO: `git commit -s -m \"message\"`\n- Run `make doc` if config/flags changed\n- Include CHANGELOG entry for user-facing changes\n\n## Investigating CI Build Failures\n\nWhen asked to investigate a CI build failure:\n\n1. **Fetch job details** using `gh api repos/cortexproject/cortex/actions/runs/<run-id>/jobs` to identify failed jobs and steps. Note: `gh run view --log` only works after the entire run completes, not just individual jobs.\n2. **Get annotations** using `gh api repos/cortexproject/cortex/check-runs/<job-id>/annotations` to surface error messages when full logs are unavailable.\n3. **Fetch full logs** once the run completes using `gh run view <run-id> --job <job-id> --log`.\n4. **Determine root cause** — distinguish between infrastructure failures (e.g., Docker Hub rate limits, runner issues) and code-related failures (e.g., test regressions). Use `git log` and `gh pr diff` to check if the failure relates to the PR's changes.\n5. **For flaky/infrastructure issues**, use `git log` and `git log -p` to trace when the failing code was introduced and which PR added it.\n6. **File GitHub issues** with the user's permission, including:\n   - The full error output in a `<details>` block (since job links can expire)\n   - Root cause analysis\n   - Which PR introduced the issue (but do not assign or tag individuals without the user's approval)\n   - Proposed solutions\n\n## Related Policies\n\nThis file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md).\n","category":"root","tokens":1464}]}