Skip to content
This repository has been archived by the owner on Jun 2, 2022. It is now read-only.
/ java-runtime-agent Public archive

Java runtime instrumentation

License

Notifications You must be signed in to change notification settings

snyk/java-runtime-agent

Repository files navigation

java-runtime-agent

Getting started

The best way to get started with the agent is to run the example project, java-woof. Head over there for a getting started guide.

Developing

Build is using gradle. You can use the wrapper, if you don't have gradle:

  • ./gradlew clean build to do a full test and build.
  • ./gradlew test to just run the unit tests.
  • ./gradlew distZip to build a distribution.

Everything is a production build by default; there is no test/debug build.

The build outputs build/libs/snyk-java-runtime-agent.jar. This must be provided to your victim JVM, as explained in docs/starting.md.

Currently, we only test Java 8. Java 9-11 will give weird errors about illegal reflective access.

Example

If you have java-goof checked out in the current directory:

# build the runtime-agent
./gradlew build

# the runtime-agent reads the config file from `snyk-agent.properties` next to the library
echo 'projectId=cf257fa0-37f9-4690-a3fc-a71f0417ded6' > build/libs/snyk-agent.properties

# start goof, with the local runtime agent
(cd java-goof && MAVEN_OPTS="-javaagent:../build/libs/snyk-java-runtime-agent.jar" mvn tomcat7:run)

It should output something like:

...
...agent initialisation: loading config from: /foo/build/libs/snyk-agent.properties
...agent initialisation: switching logging to /foo/build/libs/snyk-logs/agent-1.33.7.log

From then on, all logging will be in the named file. The tomcat startup should proceed as normal.

Code layout

This is a really weird project. Here are the restrictions that caused that:

  • No libraries, so we don't pollute anyone else's classpath
  • Performance optimisations everywhere; static method calls, concurrent counters, etc.
  • Paranoia about many things; load order, etc.

Architecture overview:

arch diagram

This doesn't mention a couple of critical classes:

  • UseCounter: the performance-critical store (in LandingZone) of whether something is called
  • ClassInfo: Transformer's helper for loading info about .jars.

Every class should have at least a sentence explaining what it does, in its documentation string.

Other docs

There's a number of documents, many relate to the project:

  • Monitoring introduction: An overview of how this type of monitoring works.
  • Initial thoughts: The initial analysis of the project specification.
  • Performance: A (mostly historical) review of the performance development of this tool.
  • Risks: Discusses the risks involved in this type of project, and how we specifically mitigate them.
  • Starting explains how to install the runtime-agent in different types of project.
  • Sample events beacon and metadata beacon files, that homebase is consuming.