{ "markdown": "

\n \n \n \n \"CodSpeed\n \n

\n\n

Optimize code performance and catch regressions early.

\n\n

Get Started ยท Documentation

\n\n
\n\n

\n \"Latest\n \"Downloads\"\n \"CI\n \"License\"\n \"Discord\n \"CodSpeed\n

\n\n[![Video Demo](./assets/readme-video.gif)](https://codspeed.io/?utm_source=github-readme)\n\n# Key features\n\n- ๐ŸŽฏ **<1% variance** in measurements using CPU simulation - no more flaky benchmarks.\n- ๐Ÿ”ฅ **Differential flamegraphs** to pinpoint exactly what got slower, commit by commit.\n- ๐Ÿ’ฌ **PR comments & status checks** showing performance impact directly in your workflow.\n- ๐Ÿ›ก๏ธ **Merge protection** to block PRs that degrade performance beyond your threshold.\n- ๐Ÿ **Multi-language support** for Python, Rust, Node.js, Go, C/C++ and more.\n- ๐Ÿ  **Run locally or in CI** - works on your machine and integrates with GitHub Actions, GitLab CI, CircleCI, and more.\n- ๐Ÿ”Œ **Plug your existing benchmarks** in less than 5 minutes - works with pytest, vitest, criterion, and more.\n\n## Installation\n\n```bash\ncurl -fsSL https://codspeed.io/install.sh | bash\n```\n\n> [!NOTE]\n> The CodSpeed CLI officially supports Ubuntu 20.04, 22.04, 24.04 and Debian 11, 12.\n> Other Linux distributions may work, but are not officially supported.\n\n## Quick Start\n\nFirst, authenticate to keep your benchmark results linked to your CodSpeed account:\n\n```bash\ncodspeed auth login\n```\n\nThe simplest way to get started is to benchmark any executable program directly:\n\n```bash\n# Benchmark a single command\ncodspeed exec -- ./my-binary --arg1 value\n\n# Benchmark a script\ncodspeed exec -- python my_script.py\n\n# Benchmark with specific instrument\ncodspeed exec --mode walltime -- node app.js\n```\n\nThis approach requires no code changes and works with any executable. CodSpeed will measure the performance provide the instrument results.\n\n## Deeper integration with harnesses using `codspeed run`\n\nFor more control and integration with your existing benchmark suite, you can use language-specific harnesses. This allows you to:\n\n- Define multiple benchmarks and keep them versioned in your codebase\n- Scope benchmarks to specific functions or modules\n- Integrate with existing benchmark suites (pytest, criterion, vitest, etc.)\n\n```bash\n# Using the Rust harness with criterion\ncodspeed run cargo codspeed run\n\n# Using the Python harness with pytest\ncodspeed run pytest ./tests --codspeed\n\n# Using the Node.js harness with vitest\ncodspeed run pnpm vitest bench\n```\n\nThese harnesses provide deeper instrumentation and allow you to write benchmarks using familiar testing frameworks.\n\n### Languages Integrations\n\nCodSpeed provides first-class integrations for multiple languages and frameworks:\n\n| Language | Repository | Supported Frameworks |\n| --------------- | ---------------------------------------------------------------- | ------------------------------------- |\n| Rust | [codspeed-rust](https://github.com/CodSpeedHQ/codspeed-rust) | `divan`, `criterion.rs`, `bencher` |\n| C/C++ | [codspeed-cpp](https://github.com/CodSpeedHQ/codspeed-cpp) | `google-benchmark` |\n| Python | [pytest-codspeed](https://github.com/CodSpeedHQ/pytest-codspeed) | `pytest` plugin |\n| Node.js | [codspeed-node](https://github.com/CodSpeedHQ/codspeed-node) | `vitest`, `tinybench`, `benchmark.js` |\n| Go | [codspeed-go](https://github.com/CodSpeedHQ/codspeed-go) | builtin `testing` package integration |\n| Zig (community) | [codspeed-zig](https://github.com/james-elicx/codspeed-zig) | custom |\n\nNeed to bench another language or framework? Open [an issue](https://github.com/CodSpeedHQ/codspeed/issues) or let us know on [Discord](https://codspeed.io/discord)!\n\n### CLI Harness: `codspeed.yml` configuration\n\nThe CLI also offers a built-in harness that allows you to define benchmarks directly.\n\nYou can define multiple `codspeed exec` benchmark targets and configure options in a `codspeed.yml` file.\nThis is useful when you want to benchmark several commands with different configurations.\n\nCreate a `codspeed.yml` file in your project root:\n\n```yaml\n# Global options applied to all benchmarks\noptions:\n warmup-time: \"0.2s\"\n max-time: 1s\n\n# List of benchmarks to run\nbenchmarks:\n - name: \"Fast operation\"\n exec: ./my_binary --mode fast\n options:\n max-rounds: 20\n\n - name: \"Slow operation\"\n exec: ./my_binary --mode slow\n options:\n max-time: 200ms\n\n - name: \"Script benchmark\"\n exec: python scripts/benchmark.py\n```\n\nThen run all benchmarks with:\n\n```bash\ncodspeed run --mode walltime\n```\n\n> [!TIP]\n> For more details on configuration options, see the [CLI documentation](https://codspeed.io/docs/cli).\n\n## Performance Instruments\n\nCodSpeed provides multiple instruments to measure different aspects of your code's performance. Choose the one that best fits your use case:\n\n### CPU Simulation\n\nSimulates CPU behavior for **<1% variance** regardless of system load. Hardware-agnostic measurements with automatic flame graphs.\n\n**Best for:** CPU-intensive code, CI regression detection, cross-platform comparison\n\n```bash\ncodspeed exec --mode simulation -- ./my-binary\n```\n\n### Memory\n\nTracks heap allocations (peak usage, count, allocation size) with eBPF profiling.\n\n**Best for:** Memory optimization, leak detection, constrained environments\n\n**Supported:** Rust, C/C++ with libc, jemalloc, mimalloc\n\n```bash\ncodspeed exec --mode memory -- ./my-binary\n```\n\n### Walltime\n\nMeasures real-world execution time including I/O, system calls, and multi-threading effects.\n\n**Best for:** API tests, I/O-heavy workloads, multi-threaded applications\n\n```bash\ncodspeed exec --mode walltime -- ./my-api-test\n```\n\n> [!WARNING]\n> Using the `walltime` mode on traditional VMs/Hosted Runners will lead to inconsistent data. For the best results, we recommend using CodSpeed Hosted Macro Runners, which are fine-tuned for performance measurement consistency.\n> Check out the [Walltime Instrument Documentation](https://docs.codspeed.io/instruments/walltime/) for more details.\n\n> [!TIP]\n> For detailed information on each instrument, see the [Instruments documentation](https://codspeed.io/docs/instruments).\n\n## Usage In CI environments\n\nRunning CodSpeed in CI allows you to automatically detect performance regressions on every pull request and track performance evolution over time.\n\n### GitHub Actions\n\nWe recommend using our official GitHub Action: [@CodSpeedHQ/action](https://github.com/CodSpeedHQ/action).\n\nHere is a sample `.github/workflows/codspeed.yml` workflow for Python:\n\n```yaml\nname: CodSpeed Benchmarks\n\non:\n push:\n branches:\n - \"main\" # or \"master\"\n pull_request:\n workflow_dispatch:\n\npermissions:\n contents: read\n id-token: write\n\njobs:\n benchmarks:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n # Set up your language/environment here\n # For Python:\n - uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n - run: pip install -r requirements.txt\n\n # Run benchmarks with CodSpeed\n - uses: CodSpeedHQ/action@v5\n with:\n mode: instrumentation\n run: pytest tests/ --codspeed\n```\n\n### GitLab CI\n\nHere is a sample `.gitlab-ci.yml` configuration for Python:\n\n```yaml\nworkflow:\n rules:\n - if: $CI_PIPELINE_SOURCE == 'merge_request_event'\n - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH\n\ncodspeed:\n stage: test\n image: python:3.12\n id_tokens:\n CODSPEED_TOKEN:\n aud: codspeed.io\n before_script:\n - pip install -r requirements.txt\n - curl -fsSL https://codspeed.io/install.sh | bash -s -- --quiet\n script:\n - codspeed run --mode simulation -- pytest tests/ --codspeed\n```\n\n### CircleCI\n\nCodSpeed supports CircleCI for repositories hosted on GitHub.\n\nHere is a sample `.circleci/config.yml` configuration for Python:\n\n```yaml\nversion: 2.1\n\njobs:\n benchmarks:\n docker:\n - image: cimg/python:3.12\n steps:\n - checkout\n - run: pip install -r requirements.txt\n - run: curl -fsSL https://codspeed.io/install.sh | bash -s -- --quiet\n - run: codspeed run --mode simulation -- pytest tests/ --codspeed\n\nworkflows:\n codspeed:\n jobs:\n - benchmarks\n```\n\nJobs authenticate with OpenID Connect (OIDC) automatically, so there is no token to store. Pull requests opened from a fork cannot mint an OIDC token: set the `CODSPEED_TOKEN` environment variable for those jobs, as described in the [CircleCI configuration documentation](https://codspeed.io/docs/integrations/ci/circleci/configuration).\n\n> [!TIP]\n> For more CI integration examples and advanced configurations, check out the [CI Integration Documentation](https://codspeed.io/docs/integrations/ci/).\n", "bytes": 10302, "sha": "2c910fcad675aaadc890f7ffc5ab64134a6e1efa8cc23a19a7a03af4ea4c84e6", "repo_slug": "codspeedhq/codspeed", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_codspeedhq_codspeed_codspeed_ee660fd2/readme" }