Agent
The agent is a native library that is attached to a JVM. Each agent opens a single, bidirectional TCP connection to the Flopsar server and keeps it open until the JVM shuts down. Over that connection the agent receives its instrumentation profile and streams back execution stacks, parameters, exceptions, and JVM metrics.
Running the Flopsar agent alongside other instrumenting agents is not recommended. If you run into problems, detach the other agents first.
Installing the agent comes down to making the native library available to your JVM and pointing it at the server:
Select the agent library for your platform and architecture (see Supported Platforms and Requirements).
Copy the library to the machine that runs your Java application.
Configure the agent by adding it to your JVM options (see Attaching the Agent and Configuration).
Restart your application.
The library is a single, self-contained file:
libflopsar.soon Linux.flopsar.dllon Windows.
No additional files need to be installed; the supporting Java classes are bundled inside the library itself.
Attaching the Agent
The agent is loaded by the JVM at startup. You can attach it in two ways. The first is to add the -agentpath option to the java command:
-agentpath:<path-to-library>=<agent-options>For example, -agentpath:/opt/flopsar/libflopsar.so=opt1,opt2 loads the agent from /opt/flopsar/libflopsar.so and passes the options opt1,opt2 to it.
There are many places where JVM options can be set, depending on the software you use (startup scripts, application server configuration, environment variables, and so on). Refer to your software's documentation for how to add extra JVM options.
The second way is to set the JAVA_TOOL_OPTIONS environment variable:
JAVA_TOOL_OPTIONS is picked up by every JVM started in an environment where it is set. Use it deliberately, and prefer per-application JVM options when you want to target a single process.
The agent attaches during JVM startup. It must be present in the JVM options when the process starts — attaching to an already-running JVM is not supported.
Configuration
The agent is configured with a comma-separated list of options, each in the form key=value, passed right after the library path in the -agentpath option. All of the following options are mandatory.
app— the application name the agent is assigned to. Use the same name for every instance of a horizontally scaled service (all running the same application code).server— the socket address of the Flopsar server, in the formhost:port. The agent initiates the connection to this address.key— the agent token (a pre-shared key) used to authenticate and encrypt the connection to the server. See Providing the Agent Token below. A complete example:
This will:
load the agent from
/opt/flopsar/libflopsar.so;assign the agent to the application MyApplication;
connect to the Flopsar server at
192.168.10.11:9000;read the agent token from the
FLOPSAR_PSKenvironment variable.
Providing the Agent Token
The key option authenticates the agent to the server and secures the connection. Its value selects where the token is read from, in the form variant:value. A token is a 256-bit key, represented as 64 hexadecimal characters.
env:<NAME>— read the token (64 hex characters) from the environment variable<NAME>. For example,key=env:FLOPSAR_PSK.file:<PATH>— read the token from a file. The file must contain exactly 64 hexadecimal characters. For example,key=file:/etc/flopsar/agent.key.hex:<VALUE>— provide the token inline as 64 hexadecimal characters. For example,key=hex:0123….
Prefer env: or file: over hex:. Command-line arguments are visible to other users and processes on the host (for example, through the process list), so an inline hex: token can be exposed. Reserve hex: for development and testing.
You generate and manage agent tokens on the server. See [Agent Tokens](/administrator-guide/agent.md#agent-tokens) for how to create a token for an application and roll it over when needed.
Last updated