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..."
}

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.

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  
}

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" }
}

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.