Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / e571f3f5b42cc2d3263e020d5f1f4c02fbb04fa1 / . / org.jacoco.doc / docroot / doc / agent.html
blob: 79c50033eb6dd6d913fb0921710d121252c05503 [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" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="UTF-8" type="text/css" />
Evgeny Mandrikov82a92ca2012-01-15 20:25:48 +0000[diff] [blame]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> &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">
29 If you use the <a href="ant.html">JaCoCo Ant tasks</a> or <a href="maven.html">JaCoCo Maven plug-in</a>
30 you don't have to care about the agent and its options directly. This is
31 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 ouput:
37</p>
38
39<ul>
40 <li>File System: At JVM termination execution data is written to a local file.</li>
41 <li>TCP Socket Server: External tools can connect to the JVM and retrieve execution data over the socket connection. Optional execution data reset and execution data dump on VM exit is possible.</li>
42 <li>TCP Socket Client: At startup the JaCoCo agent connects to a given TCP endpoint. Execution data is written to the socket connection on request. Optional execution data reset and execution data dump on VM exit is possible.</li>
43 <li>JMX: External tools can connect to the JVM and retrieve execution data over the JMX.</li>
44</ul>
45
46<p>
47 The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and
48 includes all required dependencies. A Java agent can be activated with the
49 following JVM option:
50</p>
51
52<pre>
53 -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i>
54</pre>
55
56<p>
57 The JaCoCo agent accepts the following options:
58</p>
59
60<table class="coverage">
61 <thead>
62 <tr>
63 <td>Option</td>
64 <td>Description</td>
65 <td>Default</td>
66 </tr>
67 </thead>
68 <tbody>
69 <tr>
70 <td><code>destfile</code></td>
71 <td>Path to the output file for execution data.</td>
72 <td><code>jacoco.exec</code></td>
73 </tr>
74 <tr>
75 <td><code>append</code></td>
76 <td>If set to <code>true</code> and the execution data file already
77 exists, coverage data is appended to the existing file. If set to
78 <code>false</code>, an existing execution data file will be replaced.
79 </td>
80 <td><code>true</code></td>
81 </tr>
82 <tr>
83 <td><code>includes</code></td>
84 <td>A list of class names that should be included in execution analysis.
85 The list entries are separated by a colon (<code>:</code>) and
86 may use wildcard characters (<code>*</code> and <code>?</code>).
87 Except for performance optimization or technical corner cases this
88 option is normally not required.
89 </td>
90 <td><code>*</code> (all classes)</td>
91 </tr>
92 <tr>
93 <td><code>excludes</code></td>
94 <td>A list of class names that should be excluded from execution analysis.
95 The list entries are separated by a colon (<code>:</code>) and
96 may use wildcard characters (<code>*</code> and <code>?</code>).
97 Except for performance optimization or technical corner cases this
98 option is normally not required.
99 </td>
100 <td><i>empty</i> (no excluded classes)</td>
101 </tr>
102 <tr>
103 <td><code>exclclassloader</code></td>
104 <td>A list of class loader names that should be excluded from execution
105 analysis. The list entries are separated by a colon
106 (<code>:</code>) and may use wildcard characters (<code>*</code> and
107 <code>?</code>). This option might be required in case of special
108 frameworks that conflict with JaCoCo code instrumentation, in
109 particular class loaders that do not have access to the Java runtime
110 classes.
111 </td>
112 <td><code>sun.reflect.DelegatingClassLoader</code></td>
113 </tr>
114 <tr>
115 <td><code>sessionid</code></td>
116 <td>A session identifier that is written with the execution data. Without
117 this parameter a random identifier is created by the agent.
118 </td>
119 <td><i>auto-generated</i></td>
120 </tr>
121 <tr>
122 <td><code>dumponexit</code></td>
123 <td>If set to <code>true</code> coverage data will be written on VM
124 shutdown. The dump can only be written if either <code>file</code> is
125 specified or the output is <code>tcpserver</code>/<code>tcpclient</code>
126 and a connection is open at the time when the VM terminates.
127 </td>
128 <td><code>true</code></td>
129 </tr>
130 <tr>
131 <td><code>output</code></td>
132 <td>Output method to use for writing coverage data. Valid options are:
133 <ul>
134 <li><code>file</code>: At VM termination execution data is written to
135 the file specified in the <code>destfile</code> attribute.</li>
136 <li><code>tcpserver</code>: The agent listens for incoming connections
137 on the TCP port specified by the <code>address</code> and
138 <code>port</code> attribute. Execution data is written to this
139 TCP connection.</li>
140 <li><code>tcpclient</code>: At startup the agent connects to the TCP
141 port specified by the <code>address</code> and <code>port</code>
142 attribute. Execution data is written to this TCP connection.</li>
143 <li><code>mbean</code>: The agent registers an JMX MBean under the
144 name <code>org.jacoco:type=Runtime</code>.</li>
145 </ul>
146 Please see the security considerations below.
147 </td>
148 <td><code>file</code></td>
149 </tr>
150 <tr>
151 <td><code>address</code></td>
152 <td>IP address or hostname to bind to when the output method is
153 <code>tcpserver</code> or connect to when the output method is
154 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
155 "<code>*</code>" causes the agent to accept connections on any local
156 address.
157 </td>
158 <td><i>loopback interface</i></td>
159 </tr>
160 <tr>
161 <td><code>port</code></td>
162 <td>Port to bind to when the output method is <code>tcpserver</code> or
163 connect to when the output method is <code>tcpclient</code>. In
164 <code>tcpserver</code> mode the port must be available, which means
165 that if multiple JaCoCo agents should run on the same machine,
166 different ports have to be specified.
167 </td>
168 <td><code>6300</code></td>
169 </tr>
170 </tbody>
171</table>
172
173<h2>Security Consideration for Remote Agent Control</h2>
174
175<p>
176 The ports and connections opened in <code>tcpserver</code> and
177 <code>tcpclient</code> mode do not provide any authentication mechanism. If
178 you run JaCoCo on production systems make sure that no untrusted sources have
179 access to the TCP server port, or JaCoCo TCP clients only connect to trusted
180 targets. Otherwise internal information of the application might be revealed
181 or DOS attacks are possible.
182</p>
183
184</div>
185<div class="footer">
186 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
187 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
188</div>
189
190</body>
191</html>