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.

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:

-agentpath:<>=<>

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.

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.

The second way of attaching an agent is by setting the JAVA_TOOL_OPTIONS environment variable.

$ export JAVA_TOOL_OPTIONS="-agentpath:<>=<>"

Please note, the JAVA_TOOL_OPTIONS environment variable will be picked by any JVM instance running in the environment where this variable is set.

Configuration

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

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,

The following option

-agentpath:/opt/agent/libflopsar.so=app=MyApplication,server=192.168.10.11:9000

will be evaluated as follows:

the agent will be loaded from the /opt/agent/libflopsar.so file
the agent will be attached to MyApplication
the agent will attempt to connect to the Flopsar server at 192.168.10.11:9000

Additional Options

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

Option key Default value Description

Option key	Default value	Description
`name`	Auto-generated and reset every time the agent starts	Agent instance name.
`clex`	-	A list of class loaders, that should be excluded from instrumentation. The list entries should be fully qualified class names separated by the `+` sign.
`bcp`	-	A feature, which changes the way how the `com.flopsar.Flopsar` 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 `flopsar.jar` file into the specified directory and add it to the bootstrap classloader path. If absent, the agent will load the `com.flopsar.Flopsar` class into the Bootstrap ClassLoader internally. This option is usually used if you get exceptions like `java.lang.NoClassDefFoundError: com/flopsar/Flopsar`
`qsize`	`10 MiB`	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. `30mib, 20m, 50M, 30MiB, 4gib` etc.
`disable`		Disables the Flopsar agent.

name

Auto-generated and reset every time the agent starts

Agent instance name.

clex

A list of class loaders, that should be excluded from instrumentation. The list entries should be fully qualified class names separated by the + sign.

bcp

A feature, which changes the way how the com.flopsar.Flopsar 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 flopsar.jar file into the specified directory and add it to the bootstrap classloader path. If absent, the agent will load the com.flopsar.Flopsar class into the Bootstrap ClassLoader internally. This option is usually used if you get exceptions like java.lang.NoClassDefFoundError: com/flopsar/Flopsar

qsize

10 MiB

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. 30mib, 20m, 50M, 30MiB, 4gib etc.

disable

Disables the Flopsar agent.

Last updated 1 year ago