1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> 4<head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> 7 <link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> 8 <title>JaCoCo - Java Agent</title> 9</head> 10<body> 11 12<div class="breadcrumb"> 13 <a href="../index.html" class="el_report">JaCoCo</a> > 14 <a href="index.html" class="el_group">Documentation</a> > 15 <span class="el_source">Java Agent</span> 16</div> 17<div id="content"> 18 19<h1>Java Agent</h1> 20 21<p> 22 JaCoCo uses class file instrumentation to record execution coverage data. 23 Class files are instrumented on-the-fly using a so called Java agent. This 24 mechanism allows in-memory pre-processing of all class files during class 25 loading independent of the application framework. 26</p> 27 28<p class="hint"> 29 If you use the <a href="ant.html">JaCoCo Ant tasks</a> or 30 <a href="maven.html">JaCoCo Maven plug-in</a> you don't have to care about the 31 agent and its options directly. This is transparently handled by the them. 32</p> 33 34<p> 35 The JaCoCo agent collects execution information and dumps it on request or 36 when the JVM exits. There are three different modes for execution data output: 37</p> 38 39<ul> 40 <li>File System: At JVM termination execution data is written to a local 41 file.</li> 42 <li>TCP Socket Server: External tools can connect to the JVM and retrieve 43 execution data over the socket connection. Optional execution data reset 44 and execution data dump on VM exit is possible.</li> 45 <li>TCP Socket Client: At startup the JaCoCo agent connects to a given TCP 46 endpoint. Execution data is written to the socket connection on request. 47 Optional execution data reset and execution data dump on VM exit is 48 possible.</li> 49</ul> 50 51<p> 52 The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and 53 includes all required dependencies. A Java agent can be activated with the 54 following JVM option: 55</p> 56 57<pre> 58 -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i> 59</pre> 60 61<p> 62 The JaCoCo agent accepts the following options: 63</p> 64 65<table class="coverage"> 66 <thead> 67 <tr> 68 <td>Option</td> 69 <td>Description</td> 70 <td>Default</td> 71 </tr> 72 </thead> 73 <tbody> 74 <tr> 75 <td><code>destfile</code></td> 76 <td>Path to the output file for execution data.</td> 77 <td><code>jacoco.exec</code></td> 78 </tr> 79 <tr> 80 <td><code>append</code></td> 81 <td>If set to <code>true</code> and the execution data file already 82 exists, coverage data is appended to the existing file. If set to 83 <code>false</code>, an existing execution data file will be replaced. 84 </td> 85 <td><code>true</code></td> 86 </tr> 87 <tr> 88 <td><code>includes</code></td> 89 <td>A list of class names that should be included in execution analysis. 90 The list entries are separated by a colon (<code>:</code>) and 91 may use wildcard characters (<code>*</code> and <code>?</code>). 92 Except for performance optimization or technical corner cases this 93 option is normally not required. 94 </td> 95 <td><code>*</code> (all classes)</td> 96 </tr> 97 <tr> 98 <td><code>excludes</code></td> 99 <td>A list of class names that should be excluded from execution analysis. 100 The list entries are separated by a colon (<code>:</code>) and 101 may use wildcard characters (<code>*</code> and <code>?</code>). 102 Except for performance optimization or technical corner cases this 103 option is normally not required. If you want to exclude classes from 104 the report please configure the respective report generation tool 105 accordingly. 106 </td> 107 <td><i>empty</i> (no excluded classes)</td> 108 </tr> 109 <tr> 110 <td><code>exclclassloader</code></td> 111 <td>A list of class loader names that should be excluded from execution 112 analysis. The list entries are separated by a colon 113 (<code>:</code>) and may use wildcard characters (<code>*</code> and 114 <code>?</code>). This option might be required in case of special 115 frameworks that conflict with JaCoCo code instrumentation, in 116 particular class loaders that do not have access to the Java runtime 117 classes. 118 </td> 119 <td><code>sun.reflect.DelegatingClassLoader</code></td> 120 </tr> 121 <tr> 122 <td><code>inclbootstrapclasses</code></td> 123 <td>Specifies whether also classes from the bootstrap classloader should 124 be instrumented. Use this feature with caution, it needs heavy 125 includes/excludes tuning. 126 </td> 127 <td><code>false</code></td> 128 </tr> 129 <tr> 130 <td><code>inclnolocationclasses</code></td> 131 <td>Specifies whether also classes without a source location should be 132 instrumented. Normally such classes are generated at runtime e.g. by 133 mocking frameworks and are therefore excluded by default. 134 </td> 135 <td><code>false</code></td> 136 </tr> 137 <tr> 138 <td><code>sessionid</code></td> 139 <td>A session identifier that is written with the execution data. Without 140 this parameter a random identifier is created by the agent. 141 </td> 142 <td><i>auto-generated</i></td> 143 </tr> 144 <tr> 145 <td><code>dumponexit</code></td> 146 <td>If set to <code>true</code> coverage data will be written on VM 147 shutdown. The dump can only be written if either <code>file</code> is 148 specified or the output is <code>tcpserver</code>/<code>tcpclient</code> 149 and a connection is open at the time when the VM terminates. 150 </td> 151 <td><code>true</code></td> 152 </tr> 153 <tr> 154 <td><code>output</code></td> 155 <td>Output method to use for writing coverage data. Valid options are: 156 <ul> 157 <li><code>file</code>: At VM termination execution data is written to 158 the file specified in the <code>destfile</code> attribute.</li> 159 <li><code>tcpserver</code>: The agent listens for incoming connections 160 on the TCP port specified by the <code>address</code> and 161 <code>port</code> attribute. Execution data is written to this 162 TCP connection.</li> 163 <li><code>tcpclient</code>: At startup the agent connects to the TCP 164 port specified by the <code>address</code> and <code>port</code> 165 attribute. Execution data is written to this TCP connection.</li> 166 <li><code>none</code>: Do not produce any output.</li> 167 </ul> 168 Please see the security considerations below. 169 </td> 170 <td><code>file</code></td> 171 </tr> 172 <tr> 173 <td><code>address</code></td> 174 <td>IP address or hostname to bind to when the output method is 175 <code>tcpserver</code> or connect to when the output method is 176 <code>tcpclient</code>. In <code>tcpserver</code> mode the value 177 "<code>*</code>" causes the agent to accept connections on any local 178 address. 179 </td> 180 <td><i>loopback interface</i></td> 181 </tr> 182 <tr> 183 <td><code>port</code></td> 184 <td>Port to bind to when the output method is <code>tcpserver</code> or 185 connect to when the output method is <code>tcpclient</code>. In 186 <code>tcpserver</code> mode the port must be available, which means 187 that if multiple JaCoCo agents should run on the same machine, 188 different ports have to be specified. 189 </td> 190 <td><code>6300</code></td> 191 </tr> 192 <tr> 193 <td><code>classdumpdir</code></td> 194 <td>Location relative to the working directory where all class files seen 195 by the agent are dumped to. This can be useful for debugging purposes 196 or in case of dynamically created classes for example when scripting 197 engines are used. 198 </td> 199 <td><i>no dumps</i></td> 200 </tr> 201 <tr> 202 <td><code>jmx</code></td> 203 <td>If set to <code>true</code> the agent exposes 204 <a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via 205 JMX under the name <code>org.jacoco:type=Runtime</code>. Please see 206 the security considerations below. 207 </td> 208 <td><code>false</code></td> 209 </tr> 210 </tbody> 211</table> 212 213<h2>Security Consideration for Remote Agent Control</h2> 214 215<p> 216 The ports and connections opened in <code>tcpserver</code> and 217 <code>tcpclient</code> mode and the JMX interface do not provide any 218 authentication mechanism. If you run JaCoCo on production systems make sure 219 that no untrusted sources have access to the TCP server port, or JaCoCo TCP 220 clients only connect to trusted targets. Otherwise internal information of the 221 application might be revealed or DOS attacks are possible. 222</p> 223 224</div> 225<div class="footer"> 226 <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> 227 <a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors 228</div> 229 230</body> 231</html> 232
