Universal Agent Rulebooks

On this page:

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.

Operation Mode

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, <universal_agent_home>/rulebook.

The following describes the rulebooks that apply in each mode:

Local mode: If a rulebook file named local.json exists in the directory, the Universal Agent operates in local mode. It does not attempt to contact the Controller and controller-book.json is ignored if it exists. You can put the Universal Agent into local mode by using the Universal Agent CLI or by creating local.json manually.
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.json in its own rulebook directory. If the controller-book.json file exists in the rulebook directory, from that read or a previous read, then it is used as the rulebook.
Otherwise, it operates using the default.json rulebook .

For information on creating and managing controller rulebooks, see Universal Agent REST APIs.

Polling Interval

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.

Rulebook Structure

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.

{ "name": "default",
 "comments": "Controller Connection section",
 "config": {
  "version": "4.5.0.0",
  "controller_host": "192.168.99.100",
  "controller_port": "8080",
  "account_name": "customer1",
  "account_access_key": "c61f32-nnnn"
 }

CODE

The key-value pairs in these rule-level config objects apply only to the agent defined by the rule.

"rules": [{
      "name": "Machine Agent Rule",
      "comments": "Install and start the machine agent",
      "monitor": "machine",
      "condition": "True",
      "config": {
    "state": "started"
      }
  },
  {
      "name": "Java Agent Install Rule 1",
      "comments": "Inject the Java Agent as JVMs are started",
      "monitor": "java",
      "config": {
    "state": "installed",
    "application_name": "MyApp",
    "tier_name": "MyTier",
    "node_name": "MyNode"
      }
  },
  {
      "name": "Java Agent Install Rule 2",
      "comments": "Attach the Java Agent to running JVMs",
      "monitor": "java",
      "config": {
    "state": "attached",
    "application_name": "MyApp2",
    "tier_name": "MyTier2",
    "node_name": "MyNode2"
      }
  }, 
{
      "name": "Universal Agent rule",
      "comments": "Universal Agent Default Rule",
      "monitor": "universal",
      "config": {
    "version": "4.5.0.0",
    "state": "started"
      },
      "condition": "True"
  }
 ]

CODE

The following is a complete rulebook with both header and rules in JSON format:

{ "name": "default",
 "comments": "Controller Connection section",
 "config": {
  "version": "4.5.0.0",
  "controller_host": "192.168.99.100",
  "controller_port": "8080",
  "account_name": "customer1",
  "account_access_key": "c61f32-nnnn"
 },
 "rules": [{
      "name": "Machine Agent Rule",
      "comments": "Install and start the machine agent",
      "monitor": "machine",
      "condition": "True",
      "config": {
    "state": "started"
      }
  },
  {
      "name": "Java Agent Install Rule 1",
      "comments": "Inject the Java Agent as JVMs are started",
      "monitor": "java",
      "config": {
    "state": "installed",
    "application_name": "MyApp",
    "tier_name": "MyTier",
    "node_name": "MyNode"
      }
  },
  {
      "name": "Java Agent Install Rule 2",
      "comments": "Attach the Java Agent to running JVMs",
      "monitor": "java",
      "config": {
    "state": "attached",
    "application_name": "MyApp2",
    "tier_name": "MyTier2",
    "node_name": "MyNode2"
      }
  }, 
{
      "name": "Universal Agent rule",
      "comments": "Universal Agent Default Rule",
      "monitor": "universal",
      "config": {
    "version": "4.5.0.0",
    "state": "started"
      },
      "condition": "True"
  }
 ]
}

CODE

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 config object 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, controller-info.xml.

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:

account_access_key
account_name
agent_runtime_dir
application_name
controller_host
controller_port

controller_ssl_enabled
credential_store_filename
credential_store_password
enable_orchestration
force_agent_registration

machine_path
node_name
tier_name
use_encrypted_credentials
use_simple_hostname

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:

controller_host
controller_port
controller_ssl_enabled
account_name
account_access_key

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:

"rules": [
    {
        "name": "Universal Agent rule",
        "comments": "Universal Agent rule",
        "monitor": "universal",
        "config": {
            "version": "4.5.0.0",
            "state": "started"
        },
        "condition": "True"
   }
]

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:
- java for the Java Agent
- machine for the Machine Agent
- universal for the Universal Agent
- dotnet for the .NET Agent
- analytics for the Analytics Agent
- network for 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 config properties include:
- 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.
- application_name, tier_name, and node_name: Applicable to Java Agents, these properties are equivalent to application-name, tier-name, and node-name in controller-info.xml for 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 config object.

Rulebook Strategies

Using Groups

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.

Conditional Rules

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:

"condition": "True"

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:

"condition": "platform_system == '\''Linux'\''"

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:

"condition": "platform_system == '\''Linux'\'' and universalagent_version > '\''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

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.