{"owner":"vectordotdev","repo":"vector","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# Quick Reference for Vector Development\n\nThis guide provides quick commands and coding conventions for Vector development.\n\nFor comprehensive information, see [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/DEVELOPING.md](docs/DEVELOPING.md).\n\n## Project Summary\n\nVector is a high-performance, end-to-end observability data pipeline written in Rust. It collects, transforms, and routes logs, metrics, and\ntraces from various sources to any destination. Vector is designed to be reliable, fast, and vendor-neutral, enabling dramatic cost\nreduction and improved data quality for observability infrastructure.\n\n## Project Structure\n\n### Core Directories\n\n- `/src/` - Main Rust source code\n  - `sources/` - Data ingestion components\n  - `transforms/` - Data processing and routing components\n  - `sinks/` - Data output destinations\n  - `config/` - Configuration system and validation\n  - `topology/` - Component graph management\n  - `api/` - gRPC API for management and monitoring\n  - `cli.rs` - Command-line interface\n\n- `/lib/` - Modular library crates\n  - `vector-lib/` - Unified library re-exporting core Vector components\n  - `vector-core/` - Core event system and abstractions\n  - `vector-config/` - Configuration framework with schema generation\n  - `vector-buffers/` - Buffering and backpressure management\n  - `codecs/` - Data encoding/decoding (JSON, Avro, Protobuf)\n  - `enrichment/` - Data enrichment (GeoIP, custom tables)\n  - `file-source/` - File watching and reading\n  - `prometheus-parser/` - Prometheus metrics parsing\n\n- `/config/` - Configuration examples and templates\n- `/distribution/` - Packaging and deployment configs\n  - `docker/` - Docker images (Alpine, Debian, Distroless)\n  - `kubernetes/` - Kubernetes manifests\n  - `systemd/` - SystemD service files\n  - `debian/`, `rpm/` - Linux package configurations\n\n- `/scripts/` - Build, test, and deployment automation\n- `/docs/` - Developer documentation\n- `/tests/` - Integration and E2E tests\n\n## Development Workflow\n\n### Iterative Development Process\n\nWhen working on Vector's Rust codebase, follow this iterative development cycle:\n\n1. Make code changes\n2. Run `make check-clippy` to check for linting issues\n3. Fix any issues found (use `make clippy-fix` for auto-fixes)\n4. Continue to next task or mark current task complete\n\nRun this cycle after any code modification.\n\n### Final validation step\n\nAfter the task is complete run the following `make` commands to check for errors in tests and other\ntargets.\n\n1. Run `make fmt` to format your code.\n2. Run `make test SCOPE=\"<scope>\"` to run tests. `<scope>` is a test filter passed to `cargo nextest`.\n\n## Code change workflows and validation\n\n### Rust Development (Most Common)\n\nIf you're working on Vector's Rust codebase:\n\n#### Running tests\n\n```bash\n# Run all tests\nmake test\n\n# Target a single test\nmake test SCOPE=\"test_some_function\"\n\n# Filter to a specific package\nmake test SCOPE=\"-p vector\"\n\n# Use a nextest filter expression (note the quoting)\nmake test SCOPE=\"-E 'test(foo) and not test(bar)'\"\n\n# Run tests for a specific feature only\nmake test FEATURES=\"sources-file\"\n\n# Run tests matching a substring for a specific feature only\nmake test FEATURES=\"sources-file\" SCOPE=\"truncate\"\n```\n\n#### Running integration tests\n\n```bash\n# See available integration tests:\ncargo vdev int show\n\n# Run a specific integration test\ncargo vdev int run <integration-name>\n```\n\nSee [Integration Tests](#integration-tests) section below for more details.\n\n#### If editing any markdown files\n\n```bash\nmake check-markdown\n```\n\n#### If changing any user facing documentation, including examples, component configuration or VRL functions\n\n```bash\nmake generate-docs\n```\n\n#### If modifying any external dependencies\n\nRequires `dd-rust-license-tool`\n\n```bash\nmake build-licenses\n```\n\n\n#### Before committing (recommended checks)\n\n```bash\nmake fmt                      # Format code\nmake check-fmt                # Verify formatting\nmake check-clippy             # Run Clippy linter\nmake check-markdown           # Check markdown files\nmake check-generated-docs     # Check generated documentation\nmake check-changelog-fragments  # Verify changelog\n```\n\n### Website/Docs Development (Separate Process)\n\nIf you're working on vector.dev website or documentation content:\n\n**Prerequisites:**\n\n- Hugo static site generator\n- CUE CLI tool\n- Node.js and Yarn\n- htmltest\n\n**Run the site locally:**\n\n```bash\nmake generate-docs\ncd website && make serve\n# Navigate to http://localhost:1313\n```\n\n**Build website:**\n\n```bash\ncd website\nmake cue-build\n```\n\n**Note:** Website changes use Hugo, CUE, Tailwind CSS, and TypeScript. See [website/README.md](website/README.md) for details.\n\n## Configuration Format\n\nAlways generate Vector configuration examples in **YAML** unless the user explicitly asks for TOML or JSON. YAML is Vector's recommended and default configuration format.\n\n## Common Patterns\n\n### Development Tools\n\nVector uses `cargo vdev` for most development tasks. This is a custom CLI tool that wraps common operations:\n\n```bash\ncargo vdev check rust         # Clippy\ncargo vdev check fmt          # Formatting check\ncargo vdev check events       # Event instrumentation check\ncargo vdev check licenses     # License compliance\ncargo vdev test               # Unit tests\ncargo vdev int test <name>    # Integration tests\ncargo vdev fmt                # Format code\n```\n\n### Pre-Push Hook (Optional but Recommended)\n\nCreate `.git/hooks/pre-push` with:\n\n```bash\n#!/bin/sh\nset -e\n\necho \"Format code\"\nmake fmt\n\necho \"Running pre-push checks...\"\nmake check-licenses\nmake check-fmt\nmake check-clippy\nmake check-markdown\nmake check-generated-docs\nmake check-changelog-fragments\n```\n\nThen: `chmod +x .git/hooks/pre-push`\n\n## Detailed Documentation\n\n| Topic | Document |\n| ----- | -------- |\n| Rust style patterns | [docs/RUST_STYLE.md](docs/RUST_STYLE.md) |\n| Code style rules (formatting, const strings, organization) | [STYLE.md](STYLE.md) |\n| System architecture (sources, transforms, sinks, topology) | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |\n| Component specification (naming, configuration, health checks) | [docs/specs/component.md](docs/specs/component.md) |\n| Instrumentation requirements (event/metric naming) | [docs/specs/instrumentation.md](docs/specs/instrumentation.md) |\n| How to document code changes | [docs/DOCUMENTING.md](docs/DOCUMENTING.md) |\n| Adding changelog entries | [changelog.d/README.md](changelog.d/README.md) |\n\n## Architecture Notes\n\n### Component Development\n\n- **Sources**: Ingest data from external systems\n- **Transforms**: Modify, filter, or enrich event data\n- **Sinks**: Send data to external systems\n\nComponent docs are auto-generated from code annotations. Run `make check-generated-docs` after changes.\n\n### Integration Tests\n\nIntegration tests verify Vector works with real external services. Require Docker or Podman.\n\n**Run integration tests:**\n\n```bash\n# List available tests\ncargo vdev int show\n\n# Run specific test (example: aws)\ncargo vdev int start aws # need to initiate dev environment first\ncargo vdev int test aws\n```\n\nSee [docs/DEVELOPING.md](docs/DEVELOPING.md#integration-tests) for adding new integration tests.\n\n## Git Conventions\n\n- **Commit messages:** Do NOT include co-authoring information from coding agents (i.e. avoid \"Co-Authored-By: Claude\" attribution)\n- **Pull requests:** Do NOT add \"Generated with Claude Code\" or similar footers — keep PR descriptions focused on the technical changes\n\n### Preserve Open Pull Request History\n\nBefore rewriting a branch that has been pushed, use `gh` when available to check whether the branch has an open pull request:\n\n```bash\ngh pr list --head \"$(git branch --show-current)\" --state open --json number,url\n```\n\nIf `gh` is unavailable or the check fails, assume an open pull request exists.\n\nWhen an open pull request exists, never rewrite published commits or force-push the branch. Push additional commits normally to preserve incremental review.\n\n## Creating Pull Requests\n\nBefore opening a PR, read [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) and use it as the reference for the PR body structure and title.\n"}}