PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.


Skip to end of metadata
Go to start of metadata

On this page:

In Universal Agent rulebooks, you can set configurations with either static or dynamic values. Static values use literals, such as a literal string, whereas, dynamic values are based on environment variables. For most rulebook configuration, using static values is sufficient. For an elastic environment where the identity of nodes or tiers cannot be known in advance, you may want to use dynamic configuration values to name nodes, tiers, or applications.

The following sections discuss the types of environment variables, how they are referenced in rulebooks, which agents have access to them, and how they are set. The last section provides a rulebook example using dynamic values for the configurations for rules for both the Java and Machine Agents.

Types of Environment Variables

The Universal Agent can access the three types of environment variables shown in the table below to set dynamic configuration values. 

TypeSyntaxExampleAgents with Access to Environment Variable

Java environment variables

$javaenv_<variable_name>
$javaenv_APP_NAME
Java Agent
Java system properties"${property-name}", where 'property-name' is the name of the Java system property.  
${tierName}
Java Agent
system environment variables$env_<variable_name>
$env_TIER_NAME
Java Agent, Machine Agent

How to Set Environment Variables

The following sections describe the process for defining, setting, and applying different types of environment variables.

Java Environment Variables

To set Java environment variables, you define export environment variables and then start the JVM with the environment variables as command-line arguments. The JVM will then set the Java environment variables so that they are accessible to the Universal Agent. If the Java rule applies to a particular JVM, the Universal Agent then extracts the values of each environment variable and performs symbolic substitution into the config values in the rule for each $javaenv_ reference.

The flow for setting and applying Java environment variables is illustrated in the diagram below:

For environment variable substitution, if a Java Agent is introduced into a JVM at startup (as opposed to being remote attached), the javaagent.jar file must be version 4.3 or later. The 4.3 Java Agent must be installed by the Universal Agent, but it does not need to be deployed—simply installing the 4.3 Java Agent causes the supporting javaagent.jar file to be loaded into each JVM.

Java System Properties

As with Java environmental variables, you can also set Java system properties by passing command-line arguments when you start the JVM. In addition, you can programmatically set Java system properties. If the Java rule applies to a particular JVM, the Universal Agent extracts the values of each environment variable and performs symbolic substitution into the config values in the rule for each ${system-property} reference

The flow for setting and applying Java system properties is illustrated in the diagram below:

As mentioned above, you can also programmatically set a Java system property through the System class as shown below.

Properties props = System.getProperties();
props.setProperty("tierName", "MyTier");

System Environment Variables

The method of setting system environment variables and starting the Unified Agent depends on the machine's OS version. The general process is to set system environment variables in a configuration file and then use the system-specific daemon or the CLI to start the Unified Agent. If a rule applies to either a particular JVM or system, the Universal Agent extracts the values of each system environment variable and performs symbolic substitution into the config values in the rule for each $env_ reference.

The flow for setting and applying system environment variable is illustrated in the diagram below:

Example Rulebook with Dynamic Configuration Values

The following example rulebook has rules containing dynamic configuration values for both Java and Machine Agents. For more information about the dynamic configuration values, see the explanation below the example.

{
  "name": "AD-Capital",
  "comments": "Agents for AD-Capital",
  "config": {},
  "rules": [
    {
      "name": "Java rule",
      "comments": "...comments...",
      "monitor": "java",
      "config":
      {
        "version": "4.3.0.0",
        "state": "attached",
        "application_name": "$env_APP_NAME",
        "tier_name": "${tierName}",
        "node_name": "$javaenv_APP_NAME-$javaver_NODE_NAME",
        "deploy_cmd": "...regular expression matching Java command line..."
      },
      "condition": "...boolean expression indicating status of rule..."
    },
    {
      "name": "machine-4.2.10.0",
      "monitor": "machine",
      "comments": "Update Machine Agent to 4.2.10.0",
      "config": {
        "state": "started",
        "version": "4.2.10.0",
        "application_name": "$env_APP_NAME",
        "tier_name": "$env_TIER_NAME",
        "node_name": "$env_NODE_NAME"
      },
      "condition": "True"
    },
    {
      "name": "Universal Agent rule",
      "monitor": "universal",
      "comments": "Update Universal Agent to 4.3.0.0",
      "config": {
        "state": "started",
        "version": "4.3.0.0"
      },
      "condition": "True"
    }
  ]
}

In the above rulebook example, the rule for the Java Agent contains the following attributes having values referencing either JVM environment variables, Java system properties, and system environment variables:

  • "application_name": "$env_APP_NAME" indicates that the value of the "application_name" config attribute is the value of the APP_NAME environmental variable set by the system (daemon/CLI) for which the rule applies.
  • "tier_name": "${tierName}" indicates that the value of the "tier_name" config attribute is the value of the tierName system property within a JVM for which the rule applies.
  • "node_name""$javaenv_APP_NAME-$javaver_NODE_NAME" indicates that the value of the "node_name" config attribute is the value of the APP_NAME environmental variable within a JVM for which the rule applies, concatenated with a '-', followed by the value of the NODE_NAME environmental variable within the JVM.

The rule for the Machine Agent contains the following attributes having values referencing system environment variables:

  • "application_name":"$env_APP_NAME" indicates that the value of the "application_name" config attribute is the value of the APP_NAME environmental variable set by the system (daemon/CLI) when the Universal Agent is started, for which the rule applies.

  • "tier_name": "$env_TIER_NAME" indicates that the value of the "tier_name" config attribute is the value of the TIER_NAME environmental variable set by the system (daemon/CLI) when the Universal Agent is started, for which the rule applies.

  • "node_name": "$env_NODE_NAME" indicates that the value of the "node_name" config attribute is the value of the NODE_NAME environmental variable set by the system (daemon/CLI) when the Universal Agent is started, for which the rule applies.
  • No labels