Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


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

A rulebook is a JSON-formatted configuration file that contains the rules that define runtime agent instances. Entries in the rulebook direct the Universal Agent to install, stop, or start agents.

When you start the Universal Agent, the Universal Agent applies a rulebook. The rulebook contains general settings, subject to condition evaluation logic, for the Universal Agent, along with rules for individual types of runtime agents. When you add a runtime agent rule to the rulebook, the Universal Agent subject to the rule retrieves the runtime agent from the repository and installs it 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 can run in two modes:


You create and manage controller rulebooks using the Universal Agent REST APIs. See the section "Create or Update a Rulebook".

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 to change the polling frequency.

Rulebook Structure

The basic parts of a rulebook are shown in the following example:


  • name: Name for this rulebook. 
  • comments: An optional description for this rulebook. 
  • config: Runtime agent settings that apply to all runtime agents in the rulebook. The config notably contains connection settings for the Controller. See Controller Connection Fields for more information.  
  • condition: An expression that must evaluate to true on the Universal Agent host for the rule to apply.  
  • rules: Rules contain the specific rules for controlling one or more agents. There are common fields in the agent rules and fields that are specific to the agent type. See Runtime Agent Rule Fields for more information.  

The following sections provide more information on the config and rules fields.

Controller Connection Fields 

The rulebook example above describes settings that runtime agents use to connect to the Controller and how the agent instance is identified in the Controller UI. These settings correspond to values typically configurable for the runtime agents, particularly for the Java app agent configuration file, controller-info.xml.


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 needed.

Runtime Agent Rule Fields

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 machine agent rule:


  • name: Name for this rule.
  • comments: An optional description for this rule. 
  • monitor: The runtime agent type. Valid values are: 
    • java for the Java App Agent
    • machine for the Machine 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: Agent-level configuration settings 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 fields in the sample) or globally (as illustrated by the version field). Global fields enable you to avoid repeating the field in each rule. Any value specified in the rule overrides the global value. The config fields include:
    • version: The AppDynamics version of the app agent to use
    • state: The action to be applied to the agent, such as installed, which simply 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: These are equivalent settings to the application-name, tier-name and node-name settings 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 fields, see Controller Connection Fields

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 rulebookdefault-controllerAs additional Universal Agents start and register with the controller, they join the default group. 


The resulting merged rulebook is written to controller-book.json. You should not attempt to 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. You can also create test conditions that enable or disable the rule based on the environment in the Universal Agent host. 


Instead of using dynamically evaluated conditions, you can put the static values of true or false in the condition field. When used in this way, the condition field gives you a convenient way to individually enable or disable rules.  

Uninstalling a Runtime Agent 

To uninstall a runtime agent, remove the rule for it in the rulebook and save the file.