JVM bytecode instrumentation agent for capturing exceptions and breakpoint data.
- Java 11+ (JVM)
- Gradle 8.x for building
# Download the agent JAR
curl -L https://aivory.net/agent/java/latest -o aivory-agent.jar
# Run with your application
java -javaagent:aivory-agent.jar -jar your-app.jarSet via environment variables or JVM properties:
# Environment variables
export AIVORY_API_KEY=your_api_key
export AIVORY_ENVIRONMENT=production
# Or JVM properties
java -javaagent:aivory-agent.jar \
-Daivory.api.key=your_api_key \
-Daivory.environment=production \
-jar your-app.jar| Property | Environment Variable | Default | Description |
|---|---|---|---|
aivory.api.key |
AIVORY_API_KEY |
- | API key (required) |
aivory.backend.url |
AIVORY_BACKEND_URL |
wss://api.aivory.net |
Backend URL |
aivory.environment |
AIVORY_ENVIRONMENT |
production |
Environment name |
aivory.sampling.rate |
AIVORY_SAMPLING_RATE |
1.0 |
Exception sampling rate |
aivory.capture.maxDepth |
AIVORY_MAX_DEPTH |
3 |
Max object depth |
aivory.include |
AIVORY_INCLUDE |
* |
Include patterns |
aivory.exclude |
AIVORY_EXCLUDE |
java.*,sun.* |
Exclude patterns |
cd agent-java
./gradlew buildThe agent JAR will be at build/libs/aivory-monitor-agent-*.jar.
- Bytecode Instrumentation: Uses ByteBuddy to transform classes at load time
- Exception Interception: Wraps methods to catch exceptions before they propagate
- Local Variable Capture: Uses JVMTI to access local variables at breakpoints
- WebSocket Streaming: Sends captured data to backend in real-time
- Spring Boot: Auto-configuration available
- Micronaut: Works with standard agent attachment
- Quarkus: Native mode requires GraalVM configuration
- Plain Java: Works with any Java application
Agent not loading:
- Ensure
-javaagentflag is before-jar - Check agent JAR path is correct
No data captured:
- Verify API key is set correctly
- Check include/exclude patterns
- Enable debug logging:
-Daivory.log.level=DEBUG