Full Javadoc

Author: Gabriel-Darbord

src/main/java/fr/bl/drit/flow/agent/AgentMain.java

@@ -63,10 +63,22 @@
  */
 public class AgentMain {
 
+  /**
+   * When starting the application with the agent.
+   *
+   * @param agentArgs Arguments to parse
+   * @param inst Allows instrumenting Java code
+   */
   public static void premain(String agentArgs, Instrumentation inst) {
     init(agentArgs, inst);
   }
 
+  /**
+   * When attaching the agent at runtime.
+   *
+   * @param agentArgs Arguments to parse
+   * @param inst Allows instrumenting Java code
+   */
   public static void agentmain(String agentArgs, Instrumentation inst) {
     init(agentArgs, inst);
   }
@@ -153,14 +165,9 @@ private static void init(String agentArgs, Instrumentation inst) {
 
     // === recorder setup ===
 
-    try {
-      Singletons.RECORDER = new ThreadLocalRecorder(factory, outputDir);
-    } catch (IOException e) {
-      System.err.println("[flow-agent] Failed to create writer: " + e);
-      e.printStackTrace();
-    }
+    Singletons.RECORDER = new ThreadLocalRecorder(factory, outputDir);
 
-    final String finalMappingPath = mappingPath;
+    final boolean hasMappingPath = mappingPath != null;
 
     // register shutdown hook to close recorder
     Runtime.getRuntime()
@@ -170,7 +177,7 @@ private static void init(String agentArgs, Instrumentation inst) {
                   try {
                     Singletons.RECORDER.close();
 
-                    if (finalMappingPath == null) {
+                    if (!hasMappingPath) {
                       idMapping.dump(outputDir.resolve("ids.properties"));
                     }
 

src/main/java/fr/bl/drit/flow/agent/BinaryThreadRecorder.java

@@ -159,6 +159,10 @@ public class BinaryThreadRecorder implements ThreadRecorder {
   /** Pending consecutive exits. */
   protected long pendingExits = 0L;
 
+  /**
+   * @param outputDir Path to output directory
+   * @throws IOException If an I/O error occurs when opening an output stream.
+   */
   public BinaryThreadRecorder(Path outputDir) throws IOException {
     this.fileName = "thread-" + Thread.currentThread().getId() + ".flow";
     this.out =
@@ -171,6 +175,9 @@ public BinaryThreadRecorder(Path outputDir) throws IOException {
             64 * 1024);
   }
 
+  /**
+   * @return The file name this recorder is writing to
+   */
   public String getFileName() {
     return fileName;
   }
@@ -186,6 +193,11 @@ public void exit() throws IOException {
     pendingExits++;
   }
 
+  /**
+   * Flush a pending exit event if there is one.
+   *
+   * @throws IOException If an I/O error occurs when writing to file.
+   */
   protected void flushPendingExits() throws IOException {
     if (pendingExits == 0L) {
       return;
@@ -204,6 +216,9 @@ protected void flushPendingExits() throws IOException {
    *   bit 7     : continuation (1 if more bytes follow)
    *   bits 6-0  : next 7 bits of value
    * </code></pre>
+   *
+   * @param value The positive integer to encode
+   * @throws IOException If an I/O error occurs when writing to file.
    */
   protected void writeVarInt(long value) throws IOException {
     while ((value & M_PAYLOAD_REST) != 0) {
@@ -225,6 +240,10 @@ protected void writeVarInt(long value) throws IOException {
    * </code></pre>
    *
    * Following bytes (if any) are encoded using {@link #writeVarInt(long) writeVarInt}.
+   *
+   * @param flag The event flag
+   * @param value The positive integer to encode
+   * @throws IOException If an I/O error occurs when writing to file.
    */
   protected void writeFlagAndVarInt(int flag, long value) throws IOException {
     // Extract lowest 6 bits for first byte

src/main/java/fr/bl/drit/flow/agent/FlowAdvice.java

@@ -3,7 +3,11 @@
 import java.io.IOException;
 import net.bytebuddy.asm.Advice;
 
-public class FlowAdvice {
+/**
+ * Contains the enter and exit {@link net.bytebuddy.asm.Advice Advice} methods. Their code is
+ * inserted at the start and end of instrumented methods, respectively.
+ */
+public final class FlowAdvice {
 
   /* (non-Javadoc)
   Use `inline = false` to avoid `invokedynamic` instructions which are illegal before Java 8.
@@ -14,6 +18,11 @@ public class FlowAdvice {
   The exception is then rethrown automatically to let the execution proceed normally.
   */
 
+  /**
+   * Record entering an instrumented method.
+   *
+   * @param methodId The ID of the instrumented method
+   */
   @Advice.OnMethodEnter(inline = false)
   public static void enter(@MethodId long methodId) {
     try {
@@ -23,6 +32,7 @@ public static void enter(@MethodId long methodId) {
     }
   }
 
+  /** Record exiting an instrumented method. */
   @Advice.OnMethodExit(inline = false, onThrowable = Throwable.class)
   public static void exit() {
     try {

src/main/java/fr/bl/drit/flow/agent/JsonlThreadRecorder.java

@@ -12,7 +12,12 @@
 /**
  * Call tree JSONL recorder.
  *
- * <p>Each line is either: - {"e":"enter","method":"<id>"} - {"e":"exit"}
+ * <p>Each line is either:
+ *
+ * <ul>
+ *   <li>A method enter event: {@code {"e":"enter","method":"<id>"}}
+ *   <li>A method exit event: {@code {"e":"exit"}}
+ * </ul>
  */
 public final class JsonlThreadRecorder implements ThreadRecorder {
 
@@ -21,6 +26,10 @@ public final class JsonlThreadRecorder implements ThreadRecorder {
 
   private final String fileName;
 
+  /**
+   * @param outputDir Path to output directory
+   * @throws IOException If an I/O error occurs when opening an output stream.
+   */
   public JsonlThreadRecorder(Path outputDir) throws IOException {
     this.fileName = "thread-" + Thread.currentThread().getId() + ".jsonl";
     this.out =
@@ -35,6 +44,9 @@ public JsonlThreadRecorder(Path outputDir) throws IOException {
             64 * 1024);
   }
 
+  /**
+   * @return The file name this recorder is writing to
+   */
   public String getFileName() {
     return fileName;
   }

src/main/java/fr/bl/drit/flow/agent/MethodId.java

@@ -5,6 +5,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Used in {@link FlowAdvice#enter(long)} to annotate the parameter that contains the instrumented
+ * method ID.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface MethodId {}

src/main/java/fr/bl/drit/flow/agent/MethodIdMapping.java

@@ -31,7 +31,7 @@ public MethodIdMapping() {
    *
    * @param input Path to file containing lines of "key=id" generated by {@link #dump(Path)} in a
    *     previous run.
-   * @throws IOException
+   * @throws IOException If an I/O error occurs when opening or reading the file.
    */
   public MethodIdMapping(Path input) throws IOException {
     this.keyToId = new ConcurrentHashMap<>();
@@ -53,21 +53,40 @@ public MethodIdMapping(Path input) throws IOException {
     this.nextId = new AtomicLong(max + 1);
   }
 
+  /**
+   * Get or compute a method ID for a given method.
+   *
+   * @param key Method signature
+   * @return Method ID
+   */
   public long idFor(String key) {
     return keyToId.computeIfAbsent(key, k -> nextId.getAndIncrement());
   }
 
+  /**
+   * @return Number of methods in the mapping
+   */
   public int size() {
     return keyToId.size();
   }
 
   /**
-   * Dump the mapping to a file, for potential reuse in future runs. Format is lines of "key=id".
+   * Dump the mapping to a file.
+   *
+   * @param output Path to output file
+   * @throws IOException If an I/O error occurs when opening the file.
    */
   public void dump(Path output) throws IOException {
     dump(keyToId, output);
   }
 
+  /**
+   * Dump the mapping to a file, for potential reuse in future runs. Format is lines of "key=id".
+   *
+   * @param mapping Map of signature -> ID
+   * @param output Path to output file
+   * @throws IOException If an I/O error occurs when opening or writing the file.
+   */
   public static void dump(Map<String, Long> mapping, Path output) throws IOException {
     try (BufferedWriter w =
         Files.newBufferedWriter(

src/main/java/fr/bl/drit/flow/agent/MethodIdRemapper.java

@@ -141,12 +141,13 @@ private static Map<String, Long> optimizeMappingByCounts(
   }
 
   /**
-   * Scan existing traces and mapping. Then, optimize the mapping and write it.
+   * Read existing traces and mapping. Then, optimize the mapping and write it.
    *
    * @param inputDir directory containing trace files
    * @param outputDir directory where optimized mapping will be written
    * @return path to optimized mapping file
-   * @throws IOException
+   * @throws IOException If an I/O error occurs when reading from {@code inputDir} or writing to
+   *     {@code outputDir}.
    */
   public static Path optimize(Path inputDir, Path outputDir) throws IOException {
     Path idsFile = inputDir.resolve("ids.properties");

src/main/java/fr/bl/drit/flow/agent/Recorder.java

@@ -5,9 +5,18 @@
 
 /** Specifies a recorder that is used to record flow data. */
 public interface Recorder extends Closeable {
-  /** Emit a method enter event with the given method ID. */
+  /**
+   * Emit a method enter event with the given method ID.
+   *
+   * @param methodId The ID of the method to trace
+   * @throws IOException If an I/O error occurs when emitting the event.
+   */
   void enter(long methodId) throws IOException;
 
-  /** Emit a method exit event. */
+  /**
+   * Emit a method exit event.
+   *
+   * @throws IOException If an I/O error occurs when emitting the event.
+   */
   void exit() throws IOException;
 }

src/main/java/fr/bl/drit/flow/agent/Singletons.java

@@ -1,7 +1,9 @@
 package fr.bl.drit.flow.agent;
 
+/** Global singletons used by the agent. */
 public final class Singletons {
   private Singletons() {}
 
+  /** The {@link Recorder} of method enter and exit events. */
   public static Recorder RECORDER;
 }

src/main/java/fr/bl/drit/flow/agent/ThreadLocalRecorder.java

@@ -11,7 +11,11 @@ public final class ThreadLocalRecorder implements Recorder {
   private final ThreadLocal<ThreadRecorder> local;
   private final Queue<ThreadRecorder> all = new ConcurrentLinkedQueue<>();
 
-  public ThreadLocalRecorder(ThreadRecorderFactory factory, Path outputDir) throws IOException {
+  /**
+   * @param factory Responsible for creating {@link ThreadRecorder}s
+   * @param outputDir Path to the output directory
+   */
+  public ThreadLocalRecorder(ThreadRecorderFactory factory, Path outputDir) {
     this.local =
         ThreadLocal.withInitial(
             () -> {