arex-agent-java: recording real traffic with a Java agent

The problem: test data that ages the moment you write it

The README states the motivation plainly. As an application evolves and becomes more complex, the effort required to test it thoroughly also becomes tremendous. The framework is built around a straightforward principle: using your real world data, meaning database records, service payloads and cache items, for regression testing. The summary line the project uses for that is simple is powerful.

That is a real problem in most test suites. Fixtures are written once, they drift from what the service actually accepts and returns, and the suite passes while production breaks. A corpus taken from live traffic does not have that problem, because the data came from the code that is running.

The delivery mechanism is the second half of the design. AREX provides an out-of-the-box agent file that can be attached to any application with Java 8 or later, and it dynamically weaves solid bytecode into the existing code to record the real data of live traffic, and further use and replay it for mocking, testing and debugging.

The audience is a Java team with a live service and a testing problem, and the interesting difference from the usual approach is in the mechanism, not the goal. The next section is why that matters.

Why an agent and not a proxy

The recording mechanism is described as unique, and the contrast with other tools is explicit. Instead of being a proxy like other similar frameworks, AREX sits in the background without awareness of your application, recording realistic data in live traffic, which means no intrusive code changes are required when integrating it into an existing application.

The mechanism underneath is the Java Instrumentation API, and the project says it is capable of instrumenting various libraries and frameworks that are widely used.

That choice has a concrete consequence for the data you get. A proxy sees the HTTP traffic that crosses it. An agent inside the JVM sees the data structures the libraries exchange, so a cache entry, a database result and a service payload are all recordable, and the recorded data can be replayed into those same libraries as mocks. The README's own list of what it handles spans far beyond HTTP, from the cache libraries through the persistence frameworks and the auth stack.

The instrumentation API is also the reason the setup is a JVM flag rather than a dependency. Adding a javaagent to a start command does not change the artifact you ship, and it does not require the application to know it exists, which is what makes it usable on a service you do not own the build for.

The library list, and what it tells you about coverage

The README carries a long list of supported libraries and frameworks, headed by a link to the Maven version range rules, and the list is presented as work in progress with a note that more are to be added.

The foundation entries are Java Executors, system time and dynamic type. The cache libraries are Caffeine, Guava and Spring Cache. The Spring entries cover Spring Boot 1.4 and later plus 2.x, and the Servlet API 3 and 5.

The HTTP client list is the widest one: Apache HttpClient 4.0 and later, OkHttp 3.0 to 4.11, Feign 9.0 and later, Spring OpenFeign, RestTemplate, WebClient 5.0 and later, the ning async-http-client, and the Elasticsearch client 7.x and later.

The persistence and data stores cover RedisTemplate, Jedis 2.10 and later, Redisson 3.0 and later, Lettuce 5.x and 6.x, MyBatis 3.x with MyBatis-Plus and TkMyBatis, Hibernate 5.x, and MongoDB 3.x and 4.x. The RPC entries are Apache Dubbo 2.x and 3.x plus Alibaba Dubbo 2.x. The auth entries are Spring Security 5.x, Apache Shiro 1.x, JCasbin 1.x, Auth0 jwt 3.x, and the two jjwt line items.

Reading that list as a checklist is the right way to use this project. If your service reaches a datastore or a client that is not on the list, that traffic will not be recorded, and the mock you get back will be a mock of nothing.

Enabling the agent: the javaagent flag and the config file

Enabling the instrumentation agent means configuring a javaagent flag on the JVM, and there are two ways to do it.

The first puts everything on the command line:

java -javaagent:/path/to/arex-agent.jar -Darex.service.name=my-service-name -Darex.storage.service.host=<storage.service.host:port> -jar my-application.jar

The second puts the same configuration in an arex.agent.conf file, with the service name and the storage service host:

arex.service.name=my-service-name
arex.storage.service.host=<storage.service.host:port> 

and then points the JVM at that file with a config path property:

java -javaagent:/path/to/arex-agent.jar -Darex.config.path=/path/to/arex.agent.conf -jar my-application.jar

The file route is the one to prefer for anything with more than two settings, and it is the only route that keeps the same configuration across environments, since the command line and the file hold the same keys.

Two properties of the design are worth naming. First, the agent does nothing on its own: it works along with the AREX storage service, which is a separate project, and the host and port of that service are the only mandatory configuration. Second, because the agent is a javaagent, turning it on is a start command change, which means you can enable it in a staging environment for one deployment without touching the build.

Building the agent, and the module layout behind it

Building is a Maven build, and the README gives two forms. The plain one runs mvn clean install with -DskipTests, and the versioned packaging variant adds a -Pjar-with-version profile.

The first produces arex-agent.jar in the arex-agent-jar/ folder after the build, and the second builds a jar with a version in its name. The build process supports JDK 8 through 21, and you can skip the build entirely by downloading the latest binary from the releases page.

The module layout is where the design shows. The repository is a multi-module Maven project with a parent pom.xml, and the directories are named for their role rather than for their layer in a conventional sense. There is arex-agent-bootstrap/, arex-agent-core/, arex-agent/ for the packaged artefact, and arex-attacher/, which is the piece that does the weaving. Then there is arex-instrumentation-api/ for the API the instrumented libraries talk to, arex-instrumentation-foundation/ and arex-instrumentation/ for the actual instrumentations, arex-third-party/ for the third-party library support, arex-integration-tests/, and a docs/ directory.

The split of bootstrap, core and the packaged agent is the part to notice. It separates the code that gets loaded into the target JVM from the code that runs inside it, which is a normal thing to do for a javaagent and a thing that is easy to get wrong.

The quality tooling is visible in the badges: a build workflow, SonarCloud coverage and a quality gate status. The releases are v0.4.11 from 2026-08-23, v0.4.10 from 2026-07-23 and v0.4.8 from 2024-11-29, and the last push was on 2026-09-02.

Where arex-agent-java is the wrong tool

The first limitation is the dependency on the storage service. The agent records, and the storage service holds the recordings and serves them back as mocks. Adopting the agent means adopting a second service to deploy, monitor and secure, and a network hop between your application and it. A team with one microservice and no platform capacity should weigh that against the benefit of realistic test data.

The second limitation is the coverage list, and it is the one that will decide your experience. The supported libraries are extensive but explicitly a work in progress, and the version ranges are narrow in places, with Spring Boot 1.4 and later, OkHttp 3.0 to 4.11, Jedis 2.10 and later, and WebClient 5.0 and later among them. A service on a version outside those ranges, or reaching a library that is not on the list at all, gets no recorded traffic, and the failure mode is subtle, because the application works fine and the test corpus is quietly empty.

The third is that the recording has to come from somewhere real. The whole premise is that production traffic is better test data than invented fixtures, which means you need a service that has seen real requests. A service behind an internal firewall, a batch job with no user traffic, or a service whose inputs are highly sensitive are all cases where the premise does not hold, and in the case of sensitive data you have a governance problem, because you are copying production payloads into a test system.

The alternative worth comparing is contract testing with a schema, where the consumer publishes the request and response shapes it expects and the producer verifies them in its own pipeline. The difference in approach is where the truth comes from. This agent takes the truth from a running system and replays it, which catches problems a schema cannot, such as a service that returns a value outside its declared schema. A schema catches contract drift in either direction, costs nothing to run, and needs no second service, but it only knows about the fields someone wrote down. The agent is for the team whose failures are in the data rather than in the contract, and it is the wrong shape for a team that cannot operate a storage service or cannot move production payloads around.

Editorial conclusion

arex-agent-java fits a Java team that has a real service in production and wants its test corpus taken from real requests and responses rather than invented fixtures, because the agent records the live data inside the JVM and the same recordings drive the mocks, so a regression suite stays current without anyone maintaining fixtures. It is the wrong choice for a service with no representative production traffic, for a stack whose libraries the agent does not instrument, and for a team that cannot run a second service alongside the application. Before adopting it, check the supported library list against your own stack, from the HTTP clients and the caches through to the persistence layer and the auth stack, and confirm that the storage service deployment is something your team is willing to operate, since the agent on its own only records.

Frequently asked questions

Official sources

1. arextest/arex-agent-java on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases