https://github.com/jetbrains/debugger-memory-agent
https://github.com/jetbrains/debugger-memory-agent
intellij java-agent jvm memory profiling
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jetbrains/debugger-memory-agent
- Owner: JetBrains
- License: apache-2.0
- Created: 2018-06-28T08:23:52.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-11-04T11:12:45.000Z (about 1 year ago)
- Last Synced: 2025-01-30T02:03:35.836Z (12 months ago)
- Topics: intellij, java-agent, jvm, memory, profiling
- Language: C++
- Size: 498 KB
- Stars: 24
- Watchers: 6
- Forks: 10
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[](https://www.apache.org/licenses/LICENSE-2.0)
# Memory agent
This is a native [JVMTI](https://docs.oracle.com/javase/8/docs/platform/jvmti/jvmti.html) agent for a JVM, which is currently used in the [IDEA debugger](https://www.jetbrains.com/help/idea/analyze-objects-in-the-jvm-heap.html#45c4d5cd) to perform basic heap diagnostic during the debug process. It can also be used in any project, that is running on a JVM, to attach allocation sampling listeners for [low-overhead heap profiling](https://openjdk.java.net/jeps/331) and to collect information about the heap, such as retained sizes, object reachability, and paths to closest GC roots.
# Example usage
## Allocation sampling
Using the memory agent, you can attach allocation listeners that will catch allocation sampling events and execute your code. In the example below a stack trace of each allocation is printed.
```
MemoryAgent agent = MemoryAgent.get();
agent.addAllocationListener((info) -> {
for (StackTraceElement element : info.getThread().getStackTrace()) {
System.out.println(element);
}
});
```
You can also change the [heap sampling interval](https://openjdk.java.net/jeps/331) with
```
agent.setHeapSamplingInterval(512);
```
The overhead for allocation sampling is [1-3%](https://openjdk.java.net/jeps/331) if the user-defined code is not taken into account.
## Checking for object reachability
The example below shows how to check object reachability in the heap with weak/soft/phantom reference handling.
```
MemoryAgent agent = MemoryAgent.get();
// Passing null here forces the agent to traverse heap from the GC roots
System.out.println(agent.getFirstReachableObject(null, TestClass.class));
for (TestClass instance : agent.getAllReachableObjects(null, TestClass.class)) {
System.out.println(instance);
}
```
# Using the agent in your projects
The library is published to the bintray [repository](https://bintray.com/jetbrains/intellij-third-party-dependencies/debugger-memory-agent).
## Maven
Add the external repository url:
```
jetbrains.bintray
https://jetbrains.bintray.com/intellij-third-party-dependencies
```
Then add the dependency:
```
org.jetbrains.intellij.deps
debugger-memory-agent
1.0.32
```
## Gradle
Add the external repository url:
```
repositories {
maven {
url "https://jetbrains.bintray.com/intellij-third-party-dependencies"
}
}
```
Then add the dependency:
```
dependencies {
implementation 'org.jetbrains.intellij.deps:debugger-memory-agent:1.0.32'
}
```
## Gradle Kotlin DSL
Add the external repository url:
```
repositories {
maven {
url = uri("https://jetbrains.bintray.com/intellij-third-party-dependencies")
}
}
```
Then add the dependency:
```
dependencies {
implementation("org.jetbrains.intellij.deps:debugger-memory-agent:1.0.32")
}
```
## Attaching the agent to a JVM
If the agent library doesn't meet your needs, you can still attach the agent to a JVM separately. To do so, you should compile the agent library following the steps in [CONTRIBUTING.md](CONTRIBUTING.md). Then run a JVM with the parameter:
`-agentpath:/path/to/agent/library`.
After that, you can call the memory agent's methods using the [IdeaNativeAgentProxy](test_data/proxy/src/com/intellij/memory/agent/IdeaNativeAgentProxy.java) class.
# Building and contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for building and development tips before submitting a pull request. File an issue if you find any bug or have an idea for a new feature.