# Agent

Agent is a native library, which is attached to JVMs. It runs on a JVM and its main goal is to collect data from applications running on the JVM and the JVM itself. 

Each agent is attached to a JVM. It initiates a single bidirectional TCP connection to the Flopsar server. 

Agent is started by adding the following option to a `java` command: 

<pre><code>-agentpath:&#x3C;<a data-footnote-ref href="#user-content-fn-1">path-to-agent</a>>=&#x3C;<a data-footnote-ref href="#user-content-fn-2">agent-options</a>>
</code></pre>

For example, if the option `-agentpath:/opt/flopsar/libflopsar.so=opt1,opt2` is specified, the agent will be loaded from the `/opt/flopsar/libflopsar.so` file and the configuration options `opt1,opt2` will be passed to it.

{% hint style="info" %}
There are various places where you can add your custom JVM options, it depends on the Java software you use. Please, refer to your Java software documentation for more details about adding extra JVM options.
{% endhint %}

## Configuration

Agent configuration is specified by a set of options. There are two types of settings: mandatory and optional.&#x20;

### Mandatory Options

Each option must be specified in a form: `key=value`, where `key` is an option name. They must be specified along with the agent library itself.

* **`app`** Application name, the agent is assigned to,
* **`server`** Socket address of the Flopsar server. Agents initiate connections to this server and the connections are maintained until the agents are shutdown. It should be specified in the form `IPv4:port`,
* **`home`** Path to the agent working directory. This directory contains the agent extensions and logs.

{% tabs %}
{% tab title="Example" %}
The following option

<pre class="language-java"><code class="lang-java"><strong>-agentpath:/opt/agent/libflopsar.so=app=MyApplication,server=192.168.10.11:9000,home=/opt/flopsar
</strong></code></pre>

will be evaluated as follows:

* the agent will be loaded from the `/opt/agent/libflopsar.so` file&#x20;
* the agent will be attached to *MyApplication*
* the agent will attempt to connect to the Flopsar server at `192.168.10.11:9000`
* the agent will store its logs to `/opt/flopsar` and load its extension from `/opt/flopsar/ext` directory.
  {% endtab %}
  {% endtabs %}

### Additional Options&#x20;

Each option must be specified in a form: `-Dflopsar.key=value`, where `key` is one of the following values:

<table><thead><tr><th width="152.33333333333331">Option key</th><th width="190">Default value</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Auto-generated and reset every time the agent starts</td><td>Agent instance name.</td></tr><tr><td><code>ext</code></td><td><code>org.flopsar.ext</code></td><td>A package name, which all extensions classes come from. Classes from these packages will be loaded by the agent from the ext sub-directory in the agent working directory. Note, that no class coming from the specified package will be instrumented since the agent assumes these are extension classes.</td></tr><tr><td><code>clex</code></td><td>-</td><td>A list of class loaders, that should be excluded from instrumentation. The list entries should be fully qualified class names separated by the <code>+</code> sign.</td></tr><tr><td><code>bcp</code></td><td><code>false</code></td><td>A feature, which changes the way how the <code>com.flopsar.Flopsar</code> class is loaded into the Bootstrap ClassLoader. If set to true, the agent will extract a <code>flopsar.jar</code> file into the agent home directory and add it to the bootstrap classloader path. If either absent or set to false, the agent will load the <code>com.flopsar.Flopsar</code> class into the Bootstrap ClassLoader internally. This option is usually used if you get exceptions like <code>java.lang.NoClassDefFoundError: com/flopsar/Flopsar</code></td></tr><tr><td><code>qsize</code></td><td><code>10 MiB</code></td><td>Maximum size of the agent outbound queue size. By setting this option you specify how much memory the agent can use for the queue. The value should be specified along with the unit, e.g. <code>30mib, 20m, 50M, 30MiB, 4gib</code> etc. </td></tr><tr><td><code>log.size</code></td><td><code>50 MiB</code></td><td>Maximal size a single logger file can reach. When the value is reached, the logger file is rolled.</td></tr><tr><td><code>log.cnt</code></td><td>5</td><td>Maximal number of rolled logger files.</td></tr><tr><td><code>log.debug</code></td><td><code>false</code></td><td>Sets the logger level to <code>DEBUG</code>.</td></tr></tbody></table>

[^1]: The absolute path from which to load the agent library.

[^2]: Comma-separated agent configuration options.