Guida alla strumentazione Java

1. Introduzione

In questo tutorial, parleremo dell'API di strumentazione Java. Fornisce la capacità di aggiungere byte-code alle classi Java compilate esistenti.

Parleremo anche degli agenti java e di come li usiamo per strumentare il nostro codice.

2. Configurazione

In tutto l'articolo, creeremo un'app utilizzando la strumentazione.

La nostra applicazione sarà composta da due moduli:

  1. Un'app ATM che ci permette di prelevare denaro
  2. E un agente Java che ci permetterà di misurare le prestazioni del nostro ATM misurando il tempo investito spendendo denaro

L'agente Java modificherà il byte-code ATM permettendoci di misurare il tempo di prelievo senza dover modificare l'app ATM.

Il nostro progetto avrà la seguente struttura:

com.baeldung.instrumentation base 1.0.0 pom  agent application 

Prima di entrare troppo nei dettagli della strumentazione, vediamo cos'è un agente java.

3. Che cos'è un agente Java

In generale, un agente java è solo un file jar appositamente predisposto. Utilizza l'API di strumentazione fornita dalla JVM per modificare il codice byte esistente caricato in una JVM.

Affinché un agente funzioni, dobbiamo definire due metodi:

  • premain : caricherà staticamente l'agente utilizzando il parametro -javaagent all'avvio della JVM
  • agentmain : caricherà dinamicamente l'agente nella JVM utilizzando Java Attach API

Un concetto interessante da tenere a mente è che un'implementazione JVM, come Oracle, OpenJDK e altri, può fornire un meccanismo per avviare gli agenti dinamicamente, ma non è un requisito.

Per prima cosa, vediamo come utilizzeremmo un agente Java esistente.

Dopodiché, vedremo come crearne uno da zero per aggiungere la funzionalità di cui abbiamo bisogno nel nostro byte-code.

4. Caricamento di un agente Java

Per poter utilizzare l'agente Java, dobbiamo prima caricarlo.

Abbiamo due tipi di carico:

  • statico: utilizza il valore premain per caricare l'agente utilizzando l'opzione -javaagent
  • dinamico: utilizza l' agentmain per caricare l'agente nella JVM utilizzando Java Attach API

Successivamente, daremo un'occhiata a ciascun tipo di carico e spiegheremo come funziona.

4.1. Carico statico

Il caricamento di un agente Java all'avvio dell'applicazione è chiamato caricamento statico. Il caricamento statico modifica il codice byte all'avvio prima che venga eseguito qualsiasi codice.

Tieni presente che il caricamento statico utilizza il metodo premain , che verrà eseguito prima dell'esecuzione di qualsiasi codice dell'applicazione, per farlo funzionare possiamo eseguire:

java -javaagent:agent.jar -jar application.jar

È importante notare che dovremmo sempre mettere il parametro - javaagent prima del parametro - jar .

Di seguito sono riportati i log del nostro comando:

22:24:39.296 [main] INFO - [Agent] In premain method 22:24:39.300 [main] INFO - [Agent] Transforming class MyAtm 22:24:39.407 [main] INFO - [Application] Starting ATM application 22:24:41.409 [main] INFO - [Application] Successful Withdrawal of [7] units! 22:24:41.410 [main] INFO - [Application] Withdrawal operation completed in:2 seconds! 22:24:53.411 [main] INFO - [Application] Successful Withdrawal of [8] units! 22:24:53.411 [main] INFO - [Application] Withdrawal operation completed in:2 seconds!

Possiamo vedere quando è stato eseguito il metodo premain e quando la classe MyAtm è stata trasformata. Vediamo anche i due registri delle transazioni di prelievo ATM che contengono il tempo impiegato per completare ciascuna operazione.

Ricorda che nella nostra applicazione originale non avevamo questo tempo di completamento per una transazione, è stato aggiunto dal nostro agente Java.

4.2. Carico dinamico

La procedura di caricamento di un agente Java in una JVM già in esecuzione è chiamata caricamento dinamico. L'agente viene collegato utilizzando l'API di collegamento Java.

Uno scenario più complesso è quando la nostra applicazione ATM è già in esecuzione in produzione e vogliamo aggiungere il tempo totale delle transazioni in modo dinamico senza tempi di inattività per la nostra applicazione.

Scriviamo un piccolo pezzo di codice per fare proprio questo e chiameremo questa classe AgentLoader. Per semplicità, inseriremo questa classe nel file jar dell'applicazione. Quindi il nostro file jar dell'applicazione può sia avviare la nostra applicazione che allegare il nostro agente all'applicazione ATM:

VirtualMachine jvm = VirtualMachine.attach(jvmPid); jvm.loadAgent(agentFile.getAbsolutePath()); jvm.detach();

Ora che abbiamo il nostro AgentLoader , avviamo la nostra applicazione assicurandoci che nella pausa di dieci secondi tra le transazioni, collegheremo il nostro agente Java in modo dinamico utilizzando AgentLoader .

Aggiungiamo anche il collante che ci permetterà di avviare l'applicazione o caricare l'agente.

Chiameremo questa classe Launcher e sarà la nostra classe di file jar principale:

public class Launcher { public static void main(String[] args) throws Exception { if(args[0].equals("StartMyAtmApplication")) { new MyAtmApplication().run(args); } else if(args[0].equals("LoadAgent")) { new AgentLoader().run(args); } } }

Avvio dell'applicazione

java -jar application.jar StartMyAtmApplication 22:44:21.154 [main] INFO - [Application] Starting ATM application 22:44:23.157 [main] INFO - [Application] Successful Withdrawal of [7] units!

Collegamento dell'agente Java

Dopo la prima operazione, colleghiamo l'agente java alla nostra JVM:

java -jar application.jar LoadAgent 22:44:27.022 [main] INFO - Attaching to target JVM with PID: 6575 22:44:27.306 [main] INFO - Attached to target JVM and loaded Java agent successfully 

Controlla i registri dell'applicazione

Ora che abbiamo collegato il nostro agente alla JVM vedremo che abbiamo il tempo totale di completamento per la seconda operazione di prelievo ATM.

Ciò significa che abbiamo aggiunto la nostra funzionalità al volo, mentre la nostra applicazione era in esecuzione:

22:44:27.229 [Attach Listener] INFO - [Agent] In agentmain method 22:44:27.230 [Attach Listener] INFO - [Agent] Transforming class MyAtm 22:44:33.157 [main] INFO - [Application] Successful Withdrawal of [8] units! 22:44:33.157 [main] INFO - [Application] Withdrawal operation completed in:2 seconds!

5. Creazione di un agente Java

Dopo aver appreso come utilizzare un agente, vediamo come crearne uno. Vedremo come utilizzare Javassist per modificare il byte-code e lo combineremo con alcuni metodi API di strumentazione.

Since a java agent makes use of the Java Instrumentation API, before getting too deep into creating our agent, let's see some of the most used methods in this API and a short description of what they do:

  • addTransformer – adds a transformer to the instrumentation engine
  • getAllLoadedClasses – returns an array of all classes currently loaded by the JVM
  • retransformClasses – facilitates the instrumentation of already loaded classes by adding byte-code
  • removeTransformer – unregisters the supplied transformer
  • redefineClasses – redefine the supplied set of classes using the supplied class files, meaning that the class will be fully replaced, not modified as with retransformClasses

5.1. Create the Premain and Agentmain Methods

We know that every Java agent needs at least one of the premain or agentmain methods. The latter is used for dynamic load, while the former is used to statically load a java agent into a JVM.

Let's define both of them in our agent so that we're able to load this agent both statically and dynamically:

public static void premain( String agentArgs, Instrumentation inst) { LOGGER.info("[Agent] In premain method"); String className = "com.baeldung.instrumentation.application.MyAtm"; transformClass(className,inst); } public static void agentmain( String agentArgs, Instrumentation inst) { LOGGER.info("[Agent] In agentmain method"); String className = "com.baeldung.instrumentation.application.MyAtm"; transformClass(className,inst); }

In each method, we declare the class that we want to change and then dig down to transform that class using the transformClass method.

Below is the code for the transformClass method that we defined to help us transform MyAtm class.

In this method, we find the class we want to transform and using the transform method. Also, we add the transformer to the instrumentation engine:

private static void transformClass( String className, Instrumentation instrumentation) { Class targetCls = null; ClassLoader targetClassLoader = null; // see if we can get the class using forName try { targetCls = Class.forName(className); targetClassLoader = targetCls.getClassLoader(); transform(targetCls, targetClassLoader, instrumentation); return; } catch (Exception ex) { LOGGER.error("Class [{}] not found with Class.forName"); } // otherwise iterate all loaded classes and find what we want for(Class clazz: instrumentation.getAllLoadedClasses()) { if(clazz.getName().equals(className)) { targetCls = clazz; targetClassLoader = targetCls.getClassLoader(); transform(targetCls, targetClassLoader, instrumentation); return; } } throw new RuntimeException( "Failed to find class [" + className + "]"); } private static void transform( Class clazz, ClassLoader classLoader, Instrumentation instrumentation) { AtmTransformer dt = new AtmTransformer( clazz.getName(), classLoader); instrumentation.addTransformer(dt, true); try { instrumentation.retransformClasses(clazz); } catch (Exception ex) { throw new RuntimeException( "Transform failed for: [" + clazz.getName() + "]", ex); } }

With this out of the way, let's define the transformer for MyAtm class.

5.2. Defining Our Transformer

A class transformer must implement ClassFileTransformer and implement the transform method.

We'll use Javassist to add byte-code to MyAtm class and add a log with the total ATW withdrawal transaction time:

public class AtmTransformer implements ClassFileTransformer { @Override public byte[] transform( ClassLoader loader, String className, Class classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) { byte[] byteCode = classfileBuffer; String finalTargetClassName = this.targetClassName .replaceAll("\\.", "/"); if (!className.equals(finalTargetClassName)) { return byteCode; } if (className.equals(finalTargetClassName) && loader.equals(targetClassLoader)) { LOGGER.info("[Agent] Transforming class MyAtm"); try { ClassPool cp = ClassPool.getDefault(); CtClass cc = cp.get(targetClassName); CtMethod m = cc.getDeclaredMethod( WITHDRAW_MONEY_METHOD); m.addLocalVariable( "startTime", CtClass.longType); m.insertBefore( "startTime = System.currentTimeMillis();"); StringBuilder endBlock = new StringBuilder(); m.addLocalVariable("endTime", CtClass.longType); m.addLocalVariable("opTime", CtClass.longType); endBlock.append( "endTime = System.currentTimeMillis();"); endBlock.append( "opTime = (endTime-startTime)/1000;"); endBlock.append( "LOGGER.info(\"[Application] Withdrawal operation completed in:" + "\" + opTime + \" seconds!\");"); m.insertAfter(endBlock.toString()); byteCode = cc.toBytecode(); cc.detach(); } catch (NotFoundException | CannotCompileException | IOException e) { LOGGER.error("Exception", e); } } return byteCode; } }

5.3. Creating an Agent Manifest File

Finally, in order to get a working Java agent, we'll need a manifest file with a couple of attributes.

Quindi, possiamo trovare l'elenco completo degli attributi manifest nella documentazione ufficiale del pacchetto di strumentazione.

Nel file jar finale dell'agente Java, aggiungeremo le seguenti righe al file manifest:

Agent-Class: com.baeldung.instrumentation.agent.MyInstrumentationAgent Can-Redefine-Classes: true Can-Retransform-Classes: true Premain-Class: com.baeldung.instrumentation.agent.MyInstrumentationAgent

Il nostro agente di strumentazione Java è ora completo. Per eseguirlo, fare riferimento alla sezione Caricamento di un agente Java di questo articolo.

6. Conclusione

In questo articolo abbiamo parlato dell'API di strumentazione Java. Abbiamo esaminato come caricare un agente Java in una JVM sia staticamente che dinamicamente.

Abbiamo anche esaminato il modo in cui avremmo creato il nostro agente Java da zero.

Come sempre, l'implementazione completa dell'esempio può essere trovata su Github.