Agent
Last updated
Last updated
Agent is a core component. 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 two-way TCP connection to Manager and the second one-way TCP connection to Database. The manager address is specified in the agent configuration options while the database address is retrieved from the manager.
Agents are configured by their runtime options.
-Dflopsar.id Primary 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.
-javaagent Path to your agent file flopsar-agent-X.Y.Z.jar.
-Dflopsar.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.
-Dflopsar.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:
There are some additional options, which are not mandatory.
-Dflopsar.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.
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.
-Dflopsar.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.
-Dflopsar.id.dyn Secondary identifier of a server instance. If you use this option, you must set its value V to only another JVM option, i.e. the agent will take the value of this option and execute the method:
The output of the method will be the effective value of the secondary identifier. If you use both identifiers, primary and secondary, the agent will combine them into a single, composite identifier. They will be concatenated by an underscore character. The composite identifier’s length is up to 62 characters.
-Dflopsar.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.
-Dflopsar.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.
-Dflopsar.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.
-Dflopsar.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 -Dflopsar.qsize, the latter takes precedence.
-Dflopsar.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.
For example, your extended configuration could look like this one:
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.
Please, make sure that every agent uses its own, unique identifier. If there are multiple agents with the same identifiers and they connect to the same manager, their connections will be dropped by the manager every time a new connection attempt appears from any of the agents.
If you plan to install agent in OSGi environments, make sure to add com.flopsar classes to the OSGi container class path. Please, refer to your OSGi environment documentation for details.
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.
