The Universal Agent uses rulebooks to manage the deployment and maintenance of runtime agents. This topic introduces rulebooks and strategies for applying them
Working with Rulebooks
The Universal Agent operates according to rules that you define in rulebooks. A rulebook is a JSON-formatted configuration file that can direct the Universal Agent to install, stop, or start runtime agents.
The rulebook contains general properties, subject to condition evaluation logic, for the Universal Agent itself, along with rules for individual types of runtime agents.
So for instance, when you add a runtime agent rule to the rulebook, the Universal Agent to which the rule applies retrieves the runtime agent from an agent repository and installs the agent in the
monitor directory in the Universal Agent home. The
monitor directory contains the base install directories for each runtime agent.
The Universal Agent may run in one of two modes: controller mode or local mode. The mode it uses depends on the rulebooks that it finds in the rulebook directory,
The following describes the rulebooks that apply in each mode:
- Local mode: If a rulebook file named
local.jsonexists in the directory, the Universal Agent operates in local mode. It does not attempt to contact the Controller and
controller-book.jsonis ignored if it exists. You can put the Universal Agent into local mode by using the Universal Agent CLI or by creating
- Controller mode: Otherwise, the Universal Agent operates in Controller mode. When in Controller mode, the Universal Agent tries to get the operative rulebook from the Controller. If successful, the Universal Agent writes the contents of the Controller rulebook to a file named
controller-book.jsonin its own rulebook directory. If the
controller-book.jsonfile exists in the rulebook directory, from that read or a previous read, then it is used as the rulebook.
Otherwise, it operates using the
For information on creating and managing controller rulebooks, see Universal Agent REST APIs.
The Universal Agent reads the rulebook at regular intervals and applies changes in the rulebook as they occur, reporting the event to the Controller. By default, the Universal Agent checks the rulebook every 300 seconds (5 minutes).
For testing and initial investigatory work, you may want to reduce this interval to induce more frequent polling. Use the
interval property found in
universalagent.yaml to change the polling frequency.
The basic parts of a rulebook are shown below in tabular format. The header section tab contains settings that apply globally to all runtime agents controlled by this rulebook. In this example, the values identify the Universal Agent version and the Controller connection settings. Global properties enable you to avoid repeating the property in each rule.
The rules section tab contains rules that define runtime agents, in this case, two Java Agents and one Machine Agent. The header section and each rule can contain a config object. Any value specified in the rule overrides the global value.
The key-value pairs in this config object apply globally to the agents controlled by the rulebook.
The key-value pairs in these rule-level config objects apply only to the agent defined by the rule.
The following is a complete rulebook with both header and rules in JSON format:
Rulebook Property Reference
Header Rulebook Properties
name: Name for this rulebook.
comments: An optional description for this rulebook.
config: This object contains global properties that apply to all runtime agents in the rulebook. The
configobject notably contains connection properties for the Controller. See Controller Connection Properties for more information.
rules: Rules entries contain the specific rules for controlling one or more agents. There are common properties in the agent rules and properties that are specific to the agent type. See Runtime Agent Rule Properties for more information.
The following sections provide more information on the
config object and
rules sections of the rulebook.
Controller Connection Properties
The rulebook example above shows properties that runtime agents use to connect to the Controller and how the agent instance is identified in the Controller UI. These properties correspond to values typically configurable for the runtime agents, particularly for the Java app agent configuration file,
Using the Universal Agent, you can set any of the usual properties found in the runtime agent configuration file. In the Universal Agent rulebook, the properties have the same names that are in
controller-info.xml, except that a hyphen in the
controller-info.xml property name is replaced by an underscore in the rulebook version of the property name.
Specifically, the rulebook supports the following properties:
For more information on usage, see inline comments in the
controller-info.xml file and the topic: Administer App Server Agents.
When you set the connection values in the rulebook, the Universal Agent updates the
controller-info.xml on disk for the runtime agent. The following values are taken from
universalagent.yaml if they are not specified in the rulebook:
Specifying the values in the rulebook, however, enables you to configure the Universal Agent and its configured runtime agents to talk to different Controllers, if necessary.
Runtime Agent Rule Properties
The rules section in the Universal Agent rulebook contains rules governing the presence and status of a runtime agent on the Universal Agent host. The default rulebook,
default.json, is installed with the following predefined rule:
The properties for each rule are:
name: Name for this rule.
comments: An optional description for this rule.
monitor: The agent type. Valid values are:
javafor the Java Agent
machinefor the Machine Agent
universalfor the Universal Agent
dotnetfor the .NET Agent
analyticsfor the Analytics Agent
networkfor the Network Agent
condition: A statement that must be true to be applied by a particular Universal Agent. Typically a "condition" tests an environment variable or system property on the host on which the Universal Agent runs.
config: A JSON Object containing agent-level configuration properties such as operating state, node name, and so on. These can be specified per runtime agent in the rule (as illustrated by the state and application_name properties in the sample) or globally (as illustrated by the version property in the header section). Values specified in the rule override the global value. The
version: The AppDynamics version of the app agent to use
state: The action to be applied to the agent, such as
installed, which installs the agent or
started, which both installs and starts it. For agent specific state information, see Java Agent Rules and Standalone Machine Agent Rules.
node_name: Applicable to Java Agents, these properties are equivalent to application-name, tier-name, and node-name in
controller-info.xmlfor the traditional agent configuration. They specify the business application, tier, and node by which the current monitored process is identified in the Controller UI. For additional connection related properties, see Controller Connection Properties. Other runtime agents may have agent-specific properties that can be defined in the rule-level
Universal Agent groups are a way to manage multiple Universal Agents as a logical group. By default, Universal Agents are part of the default group and run the default rulebook,
default-controller. As additional Universal Agents start and register with the controller, they join the default group.
You can create groups and add Universal Agents to them using the Universal Agent REST API.
A Universal Agent can be part of multiple groups. When the Universal Agent is added to the groups and those groups have different rulebooks, the Controller sends multiple rulebooks to the Universal Agent and the rulebooks are logically merged into a single rulebook.
The resulting merged rulebook is written to
controller-book.json. You should not modify this rulebook directly.
You can use conditions to specify criteria for applying rules. In the simplest (and default) case, the value can simply be set to "true" to enable the rule as shown in the example:
You can also create test conditions that enable or disable the rule based on the environment in the Universal Agent host.
Condition property syntax in Universal Agent rulebooks is similar to conditions in Python—the condition should evaluate to a Boolean expression with identification data keys as the operands (which should match the regular expression "[a-zA-Z0-9_]+").
To install only on Linux machines and given the "platform_system" environment variable, you could specify the following condition:
Notice that single quotes in the value are escaped using '\'.
In the following example, the condition checks for Linux and a version of the Universal Agent higher than 4.5.1:
Operators you can use are:
- Logical operators: and, or, not
- Comparison operators: ==, !=, <, <=, >, >=
- Special operators:
- Regular expression compare, where regular expression comes after the operator
- ~ (AWK-like regular expression match)
- !~ (AWK-like regular expression inverse match)
- Membership test: in
Instead of using dynamically evaluated conditions, you can put the static values of true or false in the condition property. When used in this way, the condition property gives you a convenient way to enable or disable individual rules.
Configuration templates enable you to define a set of default configuration values that apply across a set of rulebooks. See Rulebook Configuration Templates for details.
Uninstalling a Runtime Agent
To uninstall a runtime agent, remove the rule for it in the rulebook and save the file.
The Universal Agent first stops the runtime agent, if it is running, and then uninstalls the runtime agent from the application or machine and removes the directory for it.