Skip to content

Commit a29002b

Browse files
officialasishkumarofficialasishkumar
committed
docs: document Java dedup agent setup
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
1 parent d165f87 commit a29002b

2 files changed

Lines changed: 84 additions & 74 deletions

File tree

‎versioned_docs/version-4.0.0/keploy-cloud/deduplication.md‎

Lines changed: 42 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -121,47 +121,51 @@ keploy dedup --rm
121121

122122
#### 1. Pre-requisite
123123

124-
Add the Keploy Java SDK to your application:
124+
Copy the Keploy Java agent jar during your build. Do not add it as an application dependency, and do not import Keploy classes from application code.
125125

126126
```xml
127-
<dependency>
128-
<groupId>io.keploy</groupId>
129-
<artifactId>keploy-sdk</artifactId>
130-
<version>2.0.0</version>
131-
</dependency>
132-
```
133-
134-
For Spring Boot 2 or other `javax.servlet` applications, register the Keploy middleware in your main class:
135-
136-
```java
137-
import io.keploy.servlet.KeployMiddleware;
138-
import org.springframework.boot.autoconfigure.SpringBootApplication;
139-
import org.springframework.context.annotation.Import;
140-
141-
@SpringBootApplication
142-
@Import(KeployMiddleware.class)
143-
public class App {
144-
}
145-
```
146-
147-
For Spring Boot 3, Jakarta EE applications, other frameworks, or custom launchers, start the agent during application startup:
148-
149-
```java
150-
import io.keploy.dedup.KeployDedupAgent;
151-
152-
KeployDedupAgent.start();
153-
```
154-
155-
Java dynamic deduplication uses JaCoCo runtime coverage. The SDK reads coverage in-process via JaCoCo's runtime API (`org.jacoco.agent.rt.RT.getAgent()`), so attaching the JaCoCo Java agent is enough: no TCP server flags, no `--pass-through-ports`.
156-
157-
```bash
158-
java -javaagent:/path/to/org.jacoco.agent-runtime.jar -jar target/app.jar
127+
<plugin>
128+
<groupId>org.apache.maven.plugins</groupId>
129+
<artifactId>maven-dependency-plugin</artifactId>
130+
<version>3.6.1</version>
131+
<executions>
132+
<execution>
133+
<id>copy-keploy-java-agent</id>
134+
<phase>package</phase>
135+
<goals>
136+
<goal>copy</goal>
137+
</goals>
138+
<configuration>
139+
<artifactItems>
140+
<artifactItem>
141+
<groupId>io.keploy</groupId>
142+
<artifactId>keploy-sdk</artifactId>
143+
<version>2.0.1</version>
144+
<outputDirectory>${project.build.directory}</outputDirectory>
145+
<destFileName>keploy-sdk.jar</destFileName>
146+
</artifactItem>
147+
</artifactItems>
148+
</configuration>
149+
</execution>
150+
</executions>
151+
</plugin>
152+
```
153+
154+
Java dynamic deduplication uses JaCoCo runtime coverage. Attach the Keploy Java agent to start the dedup control socket, and attach the JaCoCo Java agent to provide coverage data. In the common path there are no TCP server flags and no `--pass-through-ports`.
155+
156+
```bash
157+
java \
158+
-javaagent:target/keploy-sdk.jar \
159+
-javaagent:/path/to/org.jacoco.agent-runtime.jar \
160+
-jar target/app.jar
159161
```
160162

161163
If the in-process API is unavailable for some reason (for example, an isolated class loader), the SDK transparently falls back to JaCoCo's TCP server mode. To force the fallback, launch JaCoCo in `tcpserver` mode and tell Keploy to leave that port alone:
162164

163165
```bash
164-
java -javaagent:/path/to/org.jacoco.agent-runtime.jar=address=127.0.0.1,port=36320,output=tcpserver \
166+
java \
167+
-javaagent:target/keploy-sdk.jar \
168+
-javaagent:/path/to/org.jacoco.agent-runtime.jar=address=127.0.0.1,port=36320,output=tcpserver \
165169
-jar target/app.jar
166170
```
167171

@@ -182,21 +186,23 @@ By default, the SDK scans `target/classes`, `build/classes/java/main`, and runti
182186
When you use Docker or Docker Compose, make sure the final runtime image contains:
183187

184188
- the runnable application jar,
189+
- the Keploy Java agent jar,
185190
- the JaCoCo runtime agent jar,
186191
- the compiled classes or the fat jar that contains the application classes.
187192

188193
For example:
189194

190195
```dockerfile
191196
COPY target/app.jar /app/app.jar
197+
COPY target/keploy-sdk.jar /app/keploy-sdk.jar
192198
COPY target/classes /app/target/classes
193199
COPY jacocoagent.jar /app/jacocoagent.jar
194200
```
195201

196202
Then run the app with the JaCoCo agent attached:
197203

198204
```bash
199-
java -javaagent:/app/jacocoagent.jar -jar /app/app.jar
205+
java -javaagent:/app/keploy-sdk.jar -javaagent:/app/jacocoagent.jar -jar /app/app.jar
200206
```
201207

202208
Keploy and the Java SDK exchange per-test coverage signals over `/tmp/coverage_control.sock` and `/tmp/coverage_data.sock`. For Docker and Docker Compose, Keploy injects a shared `keploy-sockets-vol:/tmp` mount into the application container and the Keploy agent container so both processes see the same socket paths.
@@ -214,7 +220,7 @@ keploy test -c "docker compose up" --container-name containerName --dedup --lang
214220
For Native, run:
215221

216222
```bash
217-
keploy test -c "java -javaagent:/path/to/org.jacoco.agent-runtime.jar -jar target/app.jar" --dedup --language java
223+
keploy test -c "java -javaagent:target/keploy-sdk.jar -javaagent:/path/to/org.jacoco.agent-runtime.jar -jar target/app.jar" --dedup --language java
218224
```
219225

220226
If the SDK falls back to the JaCoCo TCP server, also pass `--pass-through-ports <jacoco-port>` so Keploy does not try to mock the coverage-control connection.

‎versioned_docs/version-4.0.0/server/sdk-installation/java.md‎

Lines changed: 42 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
id: java
3-
title: Java SDK for Dynamic Deduplication
3+
title: Java Agent for Dynamic Deduplication
44
sidebar_label: Java
5-
description: "Configure the Keploy Java SDK for Enterprise dynamic deduplication with in-process JaCoCo coverage."
5+
description: "Configure the Keploy Java agent for Enterprise dynamic deduplication with in-process JaCoCo coverage."
66
tags:
77
- java
88
- coverage
@@ -19,56 +19,58 @@ import ProductTier from '@site/src/components/ProductTier';
1919

2020
<ProductTier tiers="Enterprise" offerings="Self-Hosted, Dedicated" />
2121

22-
The Java SDK is used for Enterprise dynamic deduplication during replay/test mode. It collects per-testcase Java coverage and sends it to Keploy Enterprise so duplicate testcases can be identified.
22+
The Keploy Java SDK is used as a Java agent for Enterprise dynamic deduplication during replay/test mode. It collects per-testcase Java coverage and sends it to Keploy Enterprise so duplicate testcases can be identified.
2323

24-
The Java SDK does not record API traffic or mock dependencies. Record your Keploy tests separately, commit the generated test fixtures when you use them in CI, and run Java dedup during `keploy test --dedup`.
24+
The Java agent does not record API traffic or mock dependencies. Record your Keploy tests separately, commit the generated test fixtures when you use them in CI, and run Java dedup during `keploy test --dedup`.
2525

2626
## Requirements
2727

2828
- Java 8, 17, or 21
29-
- `io.keploy:keploy-sdk`
29+
- `io.keploy:keploy-sdk` version with Java-agent support
3030
- JaCoCo Java agent attached to the application JVM
3131
- Keploy Enterprise with dynamic deduplication enabled
3232

33-
## Add the SDK
33+
## Copy the Keploy Java Agent
3434

35-
Add the Keploy Java SDK dependency:
35+
Copy the Keploy Java agent jar during your build. Do not add it under `<dependencies>`, and do not import Keploy classes from your application code.
3636

3737
```xml
38-
<dependency>
39-
<groupId>io.keploy</groupId>
40-
<artifactId>keploy-sdk</artifactId>
41-
<version>2.0.0</version>
42-
</dependency>
38+
<plugin>
39+
<groupId>org.apache.maven.plugins</groupId>
40+
<artifactId>maven-dependency-plugin</artifactId>
41+
<version>3.6.1</version>
42+
<executions>
43+
<execution>
44+
<id>copy-keploy-java-agent</id>
45+
<phase>package</phase>
46+
<goals>
47+
<goal>copy</goal>
48+
</goals>
49+
<configuration>
50+
<artifactItems>
51+
<artifactItem>
52+
<groupId>io.keploy</groupId>
53+
<artifactId>keploy-sdk</artifactId>
54+
<version>2.0.1</version>
55+
<outputDirectory>${project.build.directory}</outputDirectory>
56+
<destFileName>keploy-sdk.jar</destFileName>
57+
</artifactItem>
58+
</artifactItems>
59+
</configuration>
60+
</execution>
61+
</executions>
62+
</plugin>
4363
```
4464

45-
## Start the Dedup Agent
65+
## Run with the Keploy and JaCoCo Java Agents
4666

47-
For Spring Boot 2 or other `javax.servlet` applications, import the middleware:
48-
49-
```java
50-
import io.keploy.servlet.KeployMiddleware;
51-
import org.springframework.context.annotation.Import;
52-
53-
@Import(KeployMiddleware.class)
54-
public class Application {
55-
}
56-
```
57-
58-
For Spring Boot 3, Jakarta EE applications, other frameworks, or custom launchers, start the agent during application startup:
59-
60-
```java
61-
import io.keploy.dedup.KeployDedupAgent;
62-
63-
KeployDedupAgent.start();
64-
```
65-
66-
## Run with the JaCoCo Java Agent
67-
68-
The SDK reads coverage in-process via JaCoCo's runtime API (`org.jacoco.agent.rt.RT.getAgent()`), so attaching the JaCoCo agent is enough: no TCP server flags, no port choice.
67+
The SDK reads coverage in-process via JaCoCo's runtime API (`org.jacoco.agent.rt.RT.getAgent()`), so attach both agents in the application JVM: the Keploy agent starts the dedup control socket, and the JaCoCo agent provides runtime coverage.
6968

7069
```bash
71-
java -javaagent:/path/to/jacocoagent.jar -jar target/app.jar
70+
java \
71+
-javaagent:target/keploy-sdk.jar \
72+
-javaagent:/path/to/jacocoagent.jar \
73+
-jar target/app.jar
7274
```
7375

7476
If your compiled application classes are not under `target/classes` or `build/classes/java/main`, set `KEPLOY_JAVA_CLASS_DIRS`:
@@ -80,7 +82,9 @@ export KEPLOY_JAVA_CLASS_DIRS=/absolute/path/to/target/classes
8082
If the in-process API is unavailable in your environment, the SDK transparently falls back to JaCoCo's TCP server mode. To use the fallback explicitly, launch JaCoCo in `tcpserver` mode and configure `KEPLOY_JACOCO_HOST` / `KEPLOY_JACOCO_PORT` (defaults: `127.0.0.1:36320`):
8183

8284
```bash
83-
java -javaagent:/path/to/jacocoagent.jar=address=127.0.0.1,port=36320,output=tcpserver \
85+
java \
86+
-javaagent:target/keploy-sdk.jar \
87+
-javaagent:/path/to/jacocoagent.jar=address=127.0.0.1,port=36320,output=tcpserver \
8488
-jar target/app.jar
8589
```
8690

@@ -90,7 +94,7 @@ Run Keploy in test mode with dynamic deduplication enabled:
9094

9195
```bash
9296
keploy test \
93-
-c "java -javaagent:/path/to/jacocoagent.jar -jar target/app.jar" \
97+
-c "java -javaagent:target/keploy-sdk.jar -javaagent:/path/to/jacocoagent.jar -jar target/app.jar" \
9498
--dedup \
9599
--language java
96100
```

0 commit comments

Comments
 (0)