# Agent

The JVM Performance Monitoring Agent is a critical component of our software ecosystem, designed to collect data about the Java Virtual Machine's (JVM) performance, instrument methods, and transmit this data to a central server. This technical documentation provides a comprehensive overview of the agent module, its purpose, features, architecture, and usage.

The primary goal of the JVM Performance Monitoring Agent is to enable efficient monitoring and optimization of Java applications running on the JVM. By collecting performance metrics, instrumenting specific methods, and transmitting data to a server, this module empowers developers and system administrators to:

* Identify performance bottlenecks.
* Analyze resource utilization and garbage collection behavior.
* Detect inefficient code.
* Optimize application performance based on empirical data.

The JVM Performance Monitoring Agent is typically deployed alongside Java applications and initialized using JVM arguments or configuration files. Users can customize the agent's behavior by specifying which methods to instrument, the server endpoint for data transmission, and the desired data collection frequency. Detailed usage instructions and examples can be found in the user manual.

In conclusion, the JVM Performance Monitoring Agent is a vital tool for gaining insights into the performance of Java applications running on the JVM. By collecting and transmitting performance data, developers and system administrators can make informed decisions to optimize their applications, thereby enhancing efficiency and reliability.

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

{% hint style="warning" %}
It is not recommended to use the Flospar agent with other instrumenting agents. In case of any problems, detach the other agents.
{% endhint %}

## Attaching Agents

Agents can be attached to the JVM in two ways. The first one is 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 %}

The second way of attaching an agent is by setting the `JAVA_TOOL_OPTIONS` environment variable.&#x20;

<pre class="language-shell-session"><code class="lang-shell-session">$ export JAVA_TOOL_OPTIONS="-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>

{% hint style="warning" %}
Please note, the `JAVA_TOOL_OPTIONS` environment variable will be picked by any JVM instance running in the environment where this variable is set.
{% 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. It should be the same for all instances of horizontally scaled services (running the same application code).
* **`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`,

{% 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
</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`&#x20;
  {% 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>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>-</td><td>Specify a path to the directory. This is a feature, which changes the way how the <code>com.flopsar.Flopsar</code> class is loaded into the Bootstrap ClassLoader. Its value should be a path to a directory, that is writable to JVM process. If set, the agent will extract a <code>flopsar.jar</code> file into the specified directory and add it to the bootstrap classloader path. If absent, 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>disable</code></td><td></td><td>Disables the Flopsar agent.</td></tr></tbody></table>

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

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