Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 1a56c9619e03ee3e4e1b539e592e7d8b51f53a7b / . / org.jacoco.doc / docroot / doc / agent.html
blob: 59f0cdd3d36ef2ac8ef88367f2d4b542b08c87e6 [file] [log] [blame]
Marc R. Hoffmanne571f3f2012-05-13 12:18:02 +0000[diff] [blame]1<?xml version="1.0" encoding="UTF-8" ?>
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]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>
Marc R. Hoffmanne571f3f2012-05-13 12:18:02 +0000[diff] [blame]5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Evgeny Mandrikov8b212982016-06-12 17:55:49 +0200[diff] [blame]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" />
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]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> &gt;
14 <a href="index.html" class="el_group">Documentation</a> &gt;
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">
Marc R. Hoffmanne2930e72013-01-08 21:18:35 +0100[diff] [blame]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.
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]32</p>
33
34<p>
35 The JaCoCo agent collects execution information and dumps it on request or
Hemant Kumar02accc72016-12-13 03:44:15 +0530[diff] [blame]36 when the JVM exits. There are three different modes for execution data output:
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]37</p>
38
39<ul>
Marc R. Hoffmanne2930e72013-01-08 21:18:35 +0100[diff] [blame]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>
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]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.
104 </td>
105 <td><i>empty</i> (no excluded classes)</td>
106 </tr>
107 <tr>
108 <td><code>exclclassloader</code></td>
109 <td>A list of class loader names that should be excluded from execution
110 analysis. The list entries are separated by a colon
111 (<code>:</code>) and may use wildcard characters (<code>*</code> and
112 <code>?</code>). This option might be required in case of special
113 frameworks that conflict with JaCoCo code instrumentation, in
114 particular class loaders that do not have access to the Java runtime
115 classes.
116 </td>
117 <td><code>sun.reflect.DelegatingClassLoader</code></td>
118 </tr>
119 <tr>
Marc R. Hoffmann1d8389b2014-05-20 13:44:17 +0200[diff] [blame]120 <td><code>inclbootstrapclasses</code></td>
Marc R. Hoffmann310b7d12014-05-16 20:30:20 +0200[diff] [blame]121 <td>Specifies whether also classes from the bootstrap classloader should
122 be instrumented. Use this feature with caution, it needs heavy
123 includes/excludes tuning.
124 </td>
125 <td><code>false</code></td>
126 </tr>
127 <tr>
Marc R. Hoffmann26daee42016-01-12 22:33:05 +0100[diff] [blame]128 <td><code>inclnolocationclasses</code></td>
129 <td>Specifies whether also classes without a source location should be
130 instrumented. Normally such classes are generated at runtime e.g. by
131 mocking frameworks and are therefore excluded by default.
132 </td>
133 <td><code>false</code></td>
134 </tr>
135 <tr>
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]136 <td><code>sessionid</code></td>
137 <td>A session identifier that is written with the execution data. Without
138 this parameter a random identifier is created by the agent.
139 </td>
140 <td><i>auto-generated</i></td>
141 </tr>
142 <tr>
143 <td><code>dumponexit</code></td>
144 <td>If set to <code>true</code> coverage data will be written on VM
145 shutdown. The dump can only be written if either <code>file</code> is
146 specified or the output is <code>tcpserver</code>/<code>tcpclient</code>
147 and a connection is open at the time when the VM terminates.
148 </td>
149 <td><code>true</code></td>
150 </tr>
151 <tr>
152 <td><code>output</code></td>
153 <td>Output method to use for writing coverage data. Valid options are:
154 <ul>
155 <li><code>file</code>: At VM termination execution data is written to
156 the file specified in the <code>destfile</code> attribute.</li>
157 <li><code>tcpserver</code>: The agent listens for incoming connections
158 on the TCP port specified by the <code>address</code> and
159 <code>port</code> attribute. Execution data is written to this
160 TCP connection.</li>
161 <li><code>tcpclient</code>: At startup the agent connects to the TCP
162 port specified by the <code>address</code> and <code>port</code>
163 attribute. Execution data is written to this TCP connection.</li>
Evgeny Mandrikov446f1972013-01-09 18:17:11 +0100[diff] [blame]164 <li><code>none</code>: Do not produce any output.</li>
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]165 </ul>
166 Please see the security considerations below.
167 </td>
168 <td><code>file</code></td>
169 </tr>
170 <tr>
171 <td><code>address</code></td>
172 <td>IP address or hostname to bind to when the output method is
173 <code>tcpserver</code> or connect to when the output method is
174 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
175 "<code>*</code>" causes the agent to accept connections on any local
176 address.
177 </td>
178 <td><i>loopback interface</i></td>
179 </tr>
180 <tr>
181 <td><code>port</code></td>
182 <td>Port to bind to when the output method is <code>tcpserver</code> or
183 connect to when the output method is <code>tcpclient</code>. In
184 <code>tcpserver</code> mode the port must be available, which means
185 that if multiple JaCoCo agents should run on the same machine,
186 different ports have to be specified.
187 </td>
188 <td><code>6300</code></td>
189 </tr>
Marc R. Hoffmanncf41fc12012-06-30 00:15:43 +0000[diff] [blame]190 <tr>
191 <td><code>classdumpdir</code></td>
192 <td>Location relative to the working directory where all class files seen
193 by the agent are dumped to. This can be useful for debugging purposes
194 or in case of dynamically created classes for example when scripting
195 engines are used.
196 </td>
197 <td><i>no dumps</i></td>
198 </tr>
Marc R. Hoffmanne2930e72013-01-08 21:18:35 +0100[diff] [blame]199 <tr>
200 <td><code>jmx</code></td>
201 <td>If set to <code>true</code> the agent exposes
202 <a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via
203 JMX under the name <code>org.jacoco:type=Runtime</code>. Please see
204 the security considerations below.
205 </td>
206 <td><code>false</code></td>
207 </tr>
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]208 </tbody>
209</table>
210
211<h2>Security Consideration for Remote Agent Control</h2>
212
213<p>
214 The ports and connections opened in <code>tcpserver</code> and
Marc R. Hoffmanne2930e72013-01-08 21:18:35 +0100[diff] [blame]215 <code>tcpclient</code> mode and the JMX interface do not provide any
216 authentication mechanism. If you run JaCoCo on production systems make sure
217 that no untrusted sources have access to the TCP server port, or JaCoCo TCP
218 clients only connect to trusted targets. Otherwise internal information of the
219 application might be revealed or DOS attacks are possible.
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]220</p>
221
222</div>
223<div class="footer">
224 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
225 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
226</div>
227
228</body>
229</html>