| 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 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> |