Package com.bw.jtools.profiling.weaving

Class ProfilingWeaver

  • public class ProfilingWeaver
extends java.lang.Object
    Profiling by weaving instrumentation during run-time into the byte-code.
    This class implements a "Java Agent".

    JavaAgents is a JVM feature for attaching handlers to the classloaders that can manipulate classes before they are loaded.
    For details please check the documentation about package java.lang.instrument.

    The library 'Byte Buddy' is used here to inject instrumentation code that enable us to gather profiling information without any need to modify the original sources. 'Byte Buddy' is a very capable high-level API around the byte-code manipulation library ASM.

    Usage:

    To select the classes and methods to profile you need to specify regular-expressions.
    The matcher-expression can contain multiple sub-expressions, separated by blank or ';' characters.

    
     com\.myorg\..*:get.* com\.myorg\..*:print.* com\.otherlib\..*:set.*

    You can use system properties or a property-file to specify arguments.

    As system property:

    
   java -classpath myClassPath "-Dprofiling.weaver.regex=com\.myorg\..*:get.*;com\.myorg\..*:print.*;com\.otherlib\..*:set.*"
        -Dprofiling.weaver.verbose=true
        -javaagent:path/bwJProfilingWeaverAgent-1.0.jar MyMainClass ...

    As property-file:

    This is useful if e.g. you command processor has issues with the regular expressions.
    The path to the property-file needs to be expressed as URL and can be specified by the agent-argument or as system property: 

    
   java -classpath myClassPath -javaagent:path/bwJProfilingWeaverAgent-1.0.jar=file:/path/profilingWeaver.ini MyMainClass ...

   java -classpath myClassPath -Dprofiling.weaver.ini=file:/path/profilingWeaver.ini
        -javaagent:path/bwJProfilingWeaverAgent-1.0.jar MyMainClass ...
    The property-file has two settings, identical to the system-properties, but without prefix: 
    
    # Profile all getter and print-methods:
    regexp = com\.myorg\..*:get.* com\.myorg\..*:print.*
    verbose= true
    You can use any legal url that is supported by your JVM as path to the file.
    E.g. if the file is located inside the META-INF-folder of a jar file you can try to use a JAR-url: 
    
   java -classpath myClassPath -javaagent:path/bwJProfilingWeaverAgent-1.0.jar=jar:file:/path/myJar.jar!/META-INF/profiling.ini
        MyMainClass ...
    URLs always use absolute paths. As configuration via absolute paths is pain, you can use the key-word '$CODESOURCE' in you url.
    It is replaced with the path to the folder of the codebase of the agent. From there you can use relative paths, e.g. if you main-class is inside a jar that is stored in a parallel folder to the agent-jar: 
    
   java -classpath myClassPath
        -javaagent:path/bwJProfilingWeaverAgent-1.0.jar=jar:file:$CODESOURCE../apps/myJar.jar!/META-INF/profiling.ini
        MyMainClass ...
    If you are using a newer Java version with activated module-security, you may need to 'open' packages to the weaver.
    You can try to add such options to the java command-line, here for the system package java.lang:
       java --add-opens java.base/java.lang=ALL-UNNAMED --illegal-access=deny ...
    But use this only as hint, as such issues may be related to specific configurations or JVM implementations.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ARG_REGEX
      Argument for class and method matching.
      static java.lang.String ARG_VERBOSE
      Argument for verbosity.
      static java.lang.String CODE_SOURCE
      Symbol to replace in property-file URLs by code-source-location.
      static java.lang.String PROP_PREFIX
      System-Properties prefix.
      static java.lang.String PROP_PROPERTY_FILE
      System-Properties for property file in case the agent-argument is not set.

    • Constructor Summary

      Constructors 
      Constructor Description
      ProfilingWeaver()  

    • Method Summary

      Modifier and Type Method Description
      static void premain​(java.lang.String agentArgument, java.lang.instrument.Instrumentation instrumentation)
      Java-Agent entry point.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • ARG_REGEX

        public static final java.lang.String ARG_REGEX
        Argument for class and method matching.
        See Also:
        Constant Field Values

      • ARG_VERBOSE

        public static final java.lang.String ARG_VERBOSE
        Argument for verbosity.
        See Also:
        Constant Field Values

      • CODE_SOURCE

        public static final java.lang.String CODE_SOURCE
        Symbol to replace in property-file URLs by code-source-location.
        See Also:
        Constant Field Values

      • PROP_PREFIX

        public static final java.lang.String PROP_PREFIX
        System-Properties prefix.
        See Also:
        Constant Field Values

      • PROP_PROPERTY_FILE

        public static final java.lang.String PROP_PROPERTY_FILE
        System-Properties for property file in case the agent-argument is not set.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ProfilingWeaver

        public ProfilingWeaver()

    • Method Detail

      • premain

        public static void premain​(java.lang.String agentArgument,
                           java.lang.instrument.Instrumentation instrumentation)
        Java-Agent entry point.
        Parameters:
        agentArgument - The agent-argument from command line.
        instrumentation - The provided instrumentation from JVM.