Agent
Configuration
Agents are configured by their runtime options.
Agent Identifier
Every agent must have a name. Since the agent is attached to a JVM, which runs an application instance, its name must include both the application and instance name, separated by a dot, i.e.:myApp.myInstance denotes that the agent is attached to the myInstance instance of the myApp application. If you do not follow the rules of the naming convention, the resulting agent identifier will take its default values: generic.autoid, where autoid is automatically generated unique identifier.
It is recommended to give unique names to agents. If some of the agents have the same name, the data collected from these agents will be associated with this name and there will be no way to tell which data come from which agent. In other words, you will lose the information about the source of the collected data.
Mandatory Settings
All agents' options are Java system properties and should be used as such (added with -D prefix).
| Option | Description |
|---|---|
flopsar.id | Identifier of a JVM instance. It should consist of only word characters and have no more than 62 characters. If you provide a name consisting of more characters, the agent will truncate the name. |
flopsar.manager | Socket address of the Flopsar TCP server. Agents initiate connections to this server and the connections are maintained until the agents are shutdown. It should be specified in the form: host:port. |
flopsar.home | Path to the Flopsar working directory. Log files are stored in this directory. |
The Flopsar working directory must contain theext subdirectory. This is the place you put all your plugin classes.
The above options must be set otherwise, the agent will not work. For example, your configuration could look like this one:
-javaagent:/path/to/flopsar-agent-*.jar \
-Dflopsar.id=myApplication.instance23 \
-Dflopsar.manager=172.16.0.1:9000 \
-Dflopsar.home=/path/to/some/dir
Optional Settings
There are some additional options, which are not mandatory.
| Option | Description |
|---|---|
flopsar.ext.packages | Comma-separated list of packages, which all formatter classes come from. If not specified or empty, it contains only org.flopsar.ext package by default. Classes from these packages will be loaded by the agent from the ext subdirectory. No class coming from any of the specified packages will be instrumented since the agent assumes these are plugin classes. |
flopsar.cl | Comma-separated list of class loader classes, which should be instrumented. You can use this option if you want to instrument some class loader, which is not automatically instrumented by the agent. This can be useful if the agent cannot load some classes by already instrumented class loaders. This option is empty by default. |
flopsar.errline | If you want the agent to skip line numbers (in stack traces) in the instrumented methods, set this option value to false. The default value is true. |
flopsar.logsize | Total maximum size in MB of log files. By default, this value is set to 100. By setting this option you specify how much space log files can use. |
flopsar.qsize | Total maximum size of the agent outbound queue size in MB. By setting this option you specify how much memory the agent can use for the queue. |
flopsar.qratio | Ratio of agent outbound queue size to the maximum JVM memory size in percentages. By default, this value is set to 20. By setting this option you specify how much memory the agent can use. If you specify both this option and flopsar.qsize, the latter takes precedence. |
flopsar.debug | This option enables/disables additional logging for class loading. If you have problems during instrumentation regarding class loading, you can enable this feature to track, which class loader loads classes. The default value is false. |
flopsar.loglevel | This option sets the initial logger level. By default, this option is set to fine. |
Do not put your plugin classes into packages, which have the same root package as your instrumented application, e.g. if all your application classes belong to com.foo.bar.* package, make sure your plugin classes do not.
For example, your extended configuration could look like this one:
-javaagent:/path/to/flopsar-agent-VER.jar \
-Dflopsar.id=MyAgent.instance23 \
-Dflopsar.manager=172.16.0.1:9000 \
-Dflopsar.home=/path/to/some/dir \
-Dflopsar.logsize=200 \
-Dflopsar.qsize=400 \
-Dflopsar.errline=true
There are various places where you can add your custom Java properties, it depends on the Java software you use. Please, refer to your Java software documentation for more details about adding extra Java properties.
If you plan to install the agent in OSGi environments, make sure to add com.flopsar classes to the OSGi container classpath. Please, refer to your OSGi environment documentation for details.
Disabling Agent
If you want to disable the agent temporarily, without deleting all the settings, you can do it by setting a FLOSPAR_ENABLE=NO environment variable and restart the application.
Logging
By default, agents always start with fine logger level and after 2 minutes it is switched to info automatically. You can change this behavior using flopsar.loglevel option.
Log files are stored in a directory specified in flopsar.home option. The total log files' size cannot exceed the maximum size, which can be specified in flopsar.logsize option. There can be maximum five log files, which are rolled over when their size reaches the limit. Older files are overwritten by newer ones, so the total size of logs is kept under control.
Data Collecting Considerations
Although the agent is designed to collect as much data as possible, we are not able to guarantee that all the instrumented method calls data will be collected. It is because the agent priority is not to crash the application it runs on. That has some serious implications on the agent design and operation. We just favor stability and reliability over data completeness.
Each call of an instrumented method, symbol, or metric value is represented as a serialized entity called packet. As soon as the packet is created it is ready to be sent to a database. In order for the packet to be sent, it must be first put in the outbound queue. This is the point where the agent decides whether put it or not. The packet is put in the queue if and only if the connection to the database is established and there is enough space in the outbound queue (the size of the outbound queue can be customized). Otherwise, the packet is dropped. This scenario holds for each packet.