Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 1cf157a24dddf96aa1770786690dd0501f53cba3 / . / org.jacoco.doc / docroot / doc / agent.html
blob: 7d110caa7948035c88e2f676c1b2875d4115341d [file] [log] [blame]
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]1<?xml version="1.0" encoding="ISO-8859-1" ?>
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=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame]7 <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]8 <title>JaCoCo - Java Agent</title>
9</head>
10<body>
11
12<div class="breadcrumb">
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame]13 <a href="../index.html" class="el_report">JaCoCo</a> &gt;
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]14 <a href="index.html" class="el_group">Documentation</a> &gt;
15 <span class="el_source">Java Agent</span>
16</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]17<div id="content">
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]18
19<h1>Java Agent</h1>
20
21<p>
22 JaCoCo uses class file instrumentation to record execution coverage data.
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]23 Class files are instrumented on-the-fly using a so called Java agent. This
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]24 mechanism allows in-memory pre-processing of all class files during class
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]25 loading independent of the application framework.
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]26</p>
27
28<p class="hint">
29 If you use the <a href="ant.html">JaCoCo Ant tasks</a> you don't have to care
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]30 about the agent and its options directly. This is transparently handled by the
31 Ant tasks.
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]32</p>
33
34<p>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]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</ul>
44
45<p>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]46 The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and
47 includes all required dependencies. A Java agent can be activated with the
48 following JVM option:
49</p>
50
51<pre>
52 -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i>
53</pre>
54
55<p>
56 The JaCoCo agent accepts the following options:
57</p>
58
59<table class="coverage">
60 <thead>
61 <tr>
62 <td>Option</td>
63 <td>Description</td>
64 <td>Default</td>
65 </tr>
66 </thead>
67 <tbody>
68 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]69 <td><code>destfile</code></td>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]70 <td>Path to the output file for execution data.</td>
71 <td><code>jacoco.exec</code></td>
72 </tr>
73 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]74 <td><code>append</code></td>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]75 <td>If set to <code>true</code> and the execution data file already
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]76 exists, coverage data is appended to the existing file. If set to
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]77 <code>false</code>, an existing execution data file will be replaced.
78 </td>
79 <td><code>true</code></td>
80 </tr>
81 <tr>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]82 <td><code>includes</code></td>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]83 <td>A list of class names that should be included in execution analysis.
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]84 The list entries are separated by a vertical bar (<code>|</code>) and
85 may use wildcard characters (<code>*</code> and <code>?</code>).
86 Except for performance optimization or technical corner cases this
87 option is normally not required.
88 </td>
89 <td><code>*</code> (all classes)</td>
90 </tr>
91 <tr>
92 <td><code>excludes</code></td>
93 <td>A list of class names that should be excluded from execution analysis.
94 The list entries are separated by a vertical bar (<code>|</code>) and
95 may use wildcard characters (<code>*</code> and <code>?</code>).
96 Except for performance optimization or technical corner cases this
97 option is normally not required.
98 </td>
99 <td><i>empty</i> (no excluded classes)</td>
100 </tr>
101 <tr>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]102 <td><code>exclclassloader</code></td>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]103 <td>A list of class loader names that should be excluded from execution
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]104 analysis. The list entries are separated by a vertical bar
105 (<code>|</code>) and may use wildcard characters (<code>*</code> and
106 <code>?</code>). This option might be required in case of special
107 frameworks that conflict with JaCoCo code instrumentation, in
108 particular class loaders that do not have access to the Java runtime
109 classes.
110 </td>
111 <td><code>sun.reflect.DelegatingClassLoader</code></td>
112 </tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]113 <tr>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]114 <td><code>sessionid</code></td>
115 <td>A session identifier that is written with the execution data. Without
116 this parameter a random identifier is created by the agent.
117 </td>
118 <td><i>auto-generated</i></td>
119 </tr>
120 <tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]121 <td><code>dumponexit</code></td>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]122 <td>If set to <code>true</code> coverage data will be written on VM
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]123 shutdown. The dump can only be written if either <code>file</code> is
124 specified or the output is <code>tcpserver</code>/<code>tcpclient</code>
125 and a connection is open at the time when the VM terminates.
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]126 </td>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]127 <td><code>true</code></td>
128 </tr>
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]129 <tr>
130 <td><code>output</code></td>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]131 <td>Output method to use for writing coverage data. Valid options are:
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]132 <ul>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]133 <li><code>file</code>: At VM termination execution data is written to
134 the file specified in the <code>tofile</code> attribute.</li>
135 <li><code>tcpserver</code>: The agent listens for incoming connections
136 on the TCP port specified by the <code>address</code> and
137 <code>port</code> attribute. Execution data is written to this
138 TCP connection.</li>
139 <li><code>tcpclient</code>: At startup the agent connects to the TCP
140 port specified by the <code>address</code> and <code>port</code>
141 attribute. Execution data is written to this TCP connection.</li>
142 </ul>
Marc R. Hoffmann8e8480b2010-06-02 08:28:27 +0000[diff] [blame]143 Please see the security considerations below.
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]144 </td>
145 <td><code>file</code></td>
146 </tr>
147 <tr>
148 <td><code>address</code></td>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]149 <td>IP address or hostname to bind to when the output method is
150 <code>tcpserver</code> or connect to when the output method is
Marc R. Hoffmann1cf157a2010-06-04 05:54:48 +0000[diff] [blame^]151 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
152 "<code>*</code>" causes the agent to accept connections on any local
153 address.
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]154 </td>
Marc R. Hoffmann1cf157a2010-06-04 05:54:48 +0000[diff] [blame^]155 <td><i>loopback interface</i></td>
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]156 </tr>
157 <tr>
158 <td><code>port</code></td>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]159 <td>Port to bind to when the output method is <code>tcpserver</code> or
160 connect to when the output method is <code>tcpclient</code>. In
161 <code>tcpserver</code> mode the port must be available, which means
162 that if multiple JaCoCo agents should run on the same machine,
163 different ports have to be specified.
Brock Janiczakbd638302010-05-11 11:04:37 +0000[diff] [blame]164 </td>
165 <td><code>6300</code></td>
166 </tr>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]167 </tbody>
168</table>
169
Marc R. Hoffmann8e8480b2010-06-02 08:28:27 +0000[diff] [blame]170<h2>Security Consideration for Remote Agent Control</h2>
171
172<p>
173 The ports and connections opened in <code>tcpserver</code> and
174 <code>tcpclient</code> mode do not provide any authentication mechanism. If
175 you run JaCoCo on production systems make sure that no untrusted sources have
176 access to the TCP server port, or JaCoCo TCP clients only connect to trusted
177 targets. Otherwise internal information of the application might be revealed
178 or DOS attacks are possible.
179</p>
180
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]181</div>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]182<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]183 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
Marc R. Hoffmanndf6ff962010-04-09 15:31:22 +0000[diff] [blame]184 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]185</div>
186
187</body>
188</html>