On this page:

The AppDynamics Universal Agent uses a rulebook to determine which versions of the runtime agents should be installed and deployed. You can manage the deployment, versioning, and status of Analytics Agents collecting Transaction Analytics on a monitored machine by adding Analytics Agent rules to the Universal Agent rulebook. This topic describes the syntax and usage for the Analytics Agent rules.

The supported functionality includes:

  • Running the Analytics Agent as either an extension to the Standalone Machine Agent or in a standalone JVM 
  • Configuring the Analytics Agent property files, to run as either an extension to the Standalone Machine Agent or in a standalone JVM as indicated with the mode property
  • Upgrading the standalone Analytics Agents to new versions
  • Downgrading standalone Analytics Agents to prior versions
  • Using the Analytics Agent to collect Transaction Analytics

You typically run the Analytics Agent in standalone mode if you are collecting only analytics data from the target machine. If you also need to collect hardware metrics or need to run other Machine Agent extensions, you would use the machine agent mode.

When deploying the Analytics Agent on Linux using the Universal Agent, Standalone mode is not supported, you must use machine-agent mode.

If you have an existing Machine Agent running outside of Universal Agent control and you want to install the Analytics Agent, you should either manage both with the Universal Agent, or manage each separately (not using the Universal Agent).

Define Analytics Agent Rules

A monitor value of analytics identifies an Analytics Agent rule. 

The valid values for the state property for an Analytics Agent rule are:

  • installed
  • started

Analytics Agent Rules Syntax

The syntax for an Analytics Agent rulebook entry is as follows:

{
    "name": "...name of rule...",
    "comments": "...comments...",
    "monitor": "analytics",
    "config":
    {
        "mode": "machine-agent" | "standalone",
        "version": "...Analytics agent version...",
        "state": "installed" | "started",
        "controller_host": "...name of host running controller...",
        "controller_port": "...port number controller is listening on...",
        "account_name": "...controller account name...",
        "global_account_name": "...global account name...",
        "account_access_key": "controller account access key...",
        "deploy_in": [ "<machine-agent-rule-name>", ... ],
        "props": { "<prop-name-1>": "<prop-value-1>", "<prop-name-2>": "<prop-value-2>", ..., "<prop-name-n>": "<prop-value-n>" },
        "vmoptions: [ "<vmoption-1>", "<vmoption-2>",..., "<vmoption-n>" ],
        "force_recycle": "true" | "false"
    },
    "condition": "...boolean expression indicating status of rule..."
}
CODE

The name, comments, monitor, and condition properties are common to all agent rules and have no special meaning for the Analytics Agent:

  • name: A short string to identify the rule.
  • comments: A long string describing the rule's purpose.
  • monitor: Name of the target runtime agent (for Analytics Agent, must be "analytics").
  • condition: Conditions for applying this rule. A condition consists of a Boolean expression where the operands are the values collected by the environment modules.

The properties within the config object have specific meanings for the Analytics Agent. They identify the following:

  • Analytics Agent execution mode
  • Property values for the Universal Agent to use to override the default values in the analytics property files
  • Network location of the Controller that the agent connects with
  • Whether or not changes to the Analytics Agent configuration should cause the hosting Machine Agent to be recycled.
KeywordDescriptionExample
modeIndicates whether the analytics agent is to run as a machine agent (machine-agent) or as a standalone JVM (standalone)"mode": "machine-agent"

version

Identifies the version of the analytics agent to run. This is applicable only if the mode is "standalone". When running as a machine
agent extension, the analytics agent uses the same version as the machine agent  
"version": "4.5.0.0"
state

Indicates the state of the analytics agent:

  • installed: The analytics agent should be installed, but should not be started
  • started: The analytics agent should be installed and started
"state": "started"
controller_host

Identifies the name of the host that the controller the agent should connect to is running on. This property is optional in the rule; it can be inherited from the controller_host property defined in the header section of the rulebook or from the Controller identified in the universalagent.yaml file.

"controller_host": "localhost"
controller_port

Identifies the port number that the controller the agent should connect to is listening on. This property is optional in the rule; it can be inherited from the controller_host property defined in the header section of the rulebook or from the Controller identified in the universalagent.yaml file.

"controller_port": "8080"
account_name

Identifies the account name that is passed to the controller when the agent attempt to connect. This property is optional in the rule; it can be inherited from the controller_host property defined in the header section of the rulebook or from the Controller identified in the universalagent.yaml file.

"account_name": "customer1"
global_account_name

Identifies the global account name that is used to populate the http.event.accountName property in the analytics-agent.properties file. This property is optional in the rule; it can be inherited from the controller_host property defined in the header section of the rulebook or from the Controller identified in the universalagent.yaml file.

"global_account_name": 
"customer1"

account_access_key

Identifies the account access key that is passed to the Controller when the agent attempts to connect. This property is optional in the rule. The account access key can be inherited from the controller_host property defined in the header section of the rulebook or from the Controller identified in the universalagent.yaml file.

"account_access_key":

"AB1a2b3c4$123"

events_services_hostIdentifies the network name or address of the Events Service host. This value is used to populate the http.event.endpoint property in the analytics-agent.properties file. If this property is missing, then the value of the "controller_host" property is used. "event_services_host": "1.2.3.4"
events_services_portIdentifies the port that the Events Service is listening on. This value is used to populate the http.event.endpoint property in the analytics-agent.properties file. If this value is missing, then the default value 9080 is used."event_services_port": "444"
deploy_in

Applies only when the mode is machine-agent. This property identifies the Machine Agent where the Analytics Agent runs as an extension. The value is a list of one or more strings, each of which contains the name of a Machine Agent rule within the Universal Agent rulebook. This argument is required if "mode": "machine-agent" is specified. 

"deploy_in": [ "machine-agent-1" ]
props

Contains one or more property definitions. Each property definition is added (or modified, if the property already exists) in the conf/analytics-agent.properties file for the analytics agent.

"props": { "http.event.error.retryAttempts": "500" }

vmoptionsContains one or more JVM options definitions. Each JVM options is added to the conf/analytics-agent.vmoptions file"vmoptions": [ "-verbose:class" ]
force_recycle

If true is specified, then the Universal Agent restarts any Machine Agents hosting this Analytics Agent if any of the configuration arguments change. The default is false. Applicable only if "mode": "machine-agent" is specified.

"force_recycle": "true"

Example for Machine Agent Mode

This example specifies that the Analytics Agent should run as a Machine Agent extension. In this example:

  • mode: machine-agent indicates machine-agent mode

  • state: "started" indicates that the Analytics Agent should be started within the Machine Agent.
  • deploy_in: Identifies the Machine Agents where the Analytics Agent should run.
  • props: Defines a property that will be added to, or modified within, the analytics-agent.properties file of the Analytics Agent.
  • force_recycle: A value of true indicates that the hosting Machine Agent should be recycled if the any of the config properties of the Analytic Agent change.

The following example illustrates these properties.

{
      "mode": "machine-agent",
      "state": "started",
      "deploy_in": [ "machine-agent-1" ],
      "props": { "http.event.error.retryAttempts": "500" },
      "force_recycle": true  
}
CODE

Example for Standalone Mode 

This example specifies that the Analytics Agent should run in a standalone JVM. In this example:

  • mode: standalone indicates standalone mode.

  • state: started indicates that the Analytics Agent should be started
  • props: Defines a property that will be added to, or modified within, the analytics-agent.properties file of the Analytics Agent.

The following is an example of the Analytics Agent rules:

{
      "mode": "standalone",
      "version": "4.5.0.0",
      "state": "started",
      "props": { "http.event.error.retryAttempts": "500" }
}
CODE

Special Considerations for Standalone mode

When you specify "mode": "standalone" for your Analytics Agent rule, there are some special considerations: 

  • Although a rulebook can contain multiple entries defining a standalone Analytics Agent, only one Analytics Agent runs at a time. When multiple rules are present that specify "state": "started", the agent defined by the first rule is started. Analytics Agents identified by subsequent rules are not started. If other agents are currently running, they are stopped.
  • If any configuration properties change for an Analytics Agent that is currently running, that agent is restarted.