diff --git a/AGENTS.md b/AGENTS.md index 58bcb44..59a49fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,4 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +# AGENTS.md ## Project Overview @@ -88,9 +86,12 @@ The repository combines Maven and Gradle via Gradle's composite build feature: ### CodSpeed Integration Points -1. **Walltime Collection**: Modified JMH fork in `jmh-fork/jmh-core` collects walltime metrics during benchmark execution -2. **JNI Bindings**: Native code hooks (C) for precise instrumentation in `jmh-fork/jmh-core/src/main/java/io/codspeed/` -3. **CI Integration**: GitHub Actions workflows trigger CodSpeed measurement runs on `codspeed-macro` runners +1. **Walltime Collection**: Modified JMH fork in `jmh-fork/jmh-core` collects walltime metrics during benchmark execution. Java-side bindings live in `jmh-fork/jmh-core/src/main/java/io/codspeed/`. +2. **Native libraries**: Bundled under `jmh-fork/jmh-core/`: + - `native-instrument-hooks/`: shared CodSpeed instrument-hooks library (Zig/C) used to talk to the CodSpeed runner + - `native-perf-map-agent/`: perf map agent used for symbolization +3. **CodSpeed mode**: When running under CodSpeed (`isInstrumented`), the JMH fork normalizes the benchmark mode to `AverageTime` and emits raw ops/duration per iteration so the runner can compute its own statistics. +4. **CI Integration**: GitHub Actions workflows trigger CodSpeed measurement runs on `codspeed-macro` runners ### Benchmark Architecture @@ -116,13 +117,6 @@ The repository combines Maven and Gradle via Gradle's composite build feature: 4. Update version reference in root `build.gradle.kts` if needed 5. Test both Gradle and Maven examples to verify compatibility -## Profiling & Debugging - -Use `just` commands for quick profiling workflows (see `Justfile`): -- `just profile-codspeed` — walltime profiling via CodSpeed runner -- `just profile-perf` — Linux perf + flamegraph (requires Linux + JDK perf integration) -- `just profile-asprof` — async-profiler flamegraph - ## Notes - **Submodules**: Repository uses Git submodules (`.gitmodules`). Clone with `--recurse-submodules`. diff --git a/README.md b/README.md index 644333d..db011fb 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,22 @@

codspeed-jvm

-[![CI](https://github.com/AvalancheHQ/codspeed-jvm/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/AvalancheHQ/codspeed-jvm/actions/workflows/ci.yml) +[![CI](https://github.com/CodSpeedHQ/codspeed-jvm/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CodSpeedHQ/codspeed-jvm/actions/workflows/ci.yml) [![Discord](https://img.shields.io/badge/chat%20on-discord-7289da.svg)](https://discord.com/invite/MxpaCfKSqF) -[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/AvalancheHQ/codspeed-jvm) +[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/CodSpeedHQ/codspeed-jvm)
This repo contains the CodSpeed integration for JVM-based projects using [JMH](https://github.com/openjdk/jmh): - [`jmh-fork`](./jmh-fork/): Forked JMH with CodSpeed walltime result collection -- [`instrument-hooks-jvm`](./instrument-hooks-jvm/): JNI bindings for CodSpeed [instrument hooks](https://github.com/CodSpeedHQ/instrument-hooks) -- [`example`](./example/): Example JMH benchmarks +- [`examples`](./examples/): Example JMH benchmarks (Gradle and Maven) ## Usage Add the CodSpeed JMH fork to your project and write benchmarks as you normally would with JMH. When running your benchmarks in CI with CodSpeed, the results will be automatically collected and reported. -For information on how to integrate it, see the [CodSpeed documentation](https://codspeed.io/docs). If you need further information to integrate CodSpeed to your project, please feel free to open an issue or ask for help on our discord server. +For information on how to integrate it, see the [CodSpeed documentation](https://codspeed.io/docs). If you need further information to integrate CodSpeed to your project, please feel free to open an issue or ask for help on our [Discord server](https://discord.com/invite/MxpaCfKSqF). ## Local Usage @@ -29,19 +28,14 @@ For information on how to integrate it, see the [CodSpeed documentation](https:/ ### Setup -1. Build and install the instrument hooks to your local Maven repository: -```bash -./gradlew :instrument-hooks-jvm:publishToMavenLocal -``` - -2. Build and install the JMH fork: +1. Build and install the JMH fork to your local Maven repository: ```bash cd jmh-fork && mvn clean install -DskipTests -q ``` -3. Run the example benchmarks: +2. Run the example benchmarks: ```bash -./gradlew :example:jmh +./gradlew :examples:example-gradle:jmh ``` ### Running with CodSpeed locally @@ -49,5 +43,5 @@ cd jmh-fork && mvn clean install -DskipTests -q To run the benchmarks with CodSpeed locally, you need to install the [CodSpeed runner](https://codspeed.io/docs): ```bash -codspeed run --mode walltime -- ./gradlew :example:jmh +codspeed run --mode walltime -- ./gradlew :examples:example-gradle:jmh ```