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:

This topic describes AppDynamics Universal Agent syntax for Java Agent rules. 

About Java Agent Rules

You can manage the deployment, versioning, and status of Java Agents on a monitored machine with Java Agent rules. A Universal Agent rule with a monitor value of java defines a Java Agent rule.

A Java Agent rule contains common elements for Universal Agent rules, such as the name, description and monitor type of the agent. It also includes elements that are unique to Java rules, however.

The following shows a simple example of a Java Agent rule: 

{
    "name": "Java Rule 1",
    "comments": "Java agent rule",
    "monitor": "java",
    "config":
    {
        "version": "4.3.0.0",
        "state": "started",
        "application_name": "My Application",
        "tier_name": "Commerce Tier",
        "node_name_prefix": "$network_hostname.Commerce",
        "deploy_cmd": ".*-Dnode_type=commerce.*",
        "do_not_deploy_cmd": ".*-Dproduction=true.*"
    }
}


The state field determines how the Universal Agent loads the Java Agent to target JVMs. In this case, the state is started, which causes the Java agent to be automatically deployed into JVMs as they start. The following section provides more information on the state options. See Java Agent Rule Syntax Reference for more information about the other fields in the example. 

Deployment Options

You can deploy the Java Agent with the Universal Agent using one of the following approaches:

  • Attach: Installs the Java Agent and if auto-java is enabled, automatically deploys the Java Agent into the JVM at startup time. If the target JVM is already running, then the Java Agent attempts to remotely attach itself to the JVM without forcing a restart, regardless of whether auto-java is enabled.  
  • Started: Installs the Java Agent and if auto-java is enabled, deploys the Java Agent into the JVM at JVM startup. If the JVM is already running, the agent does not try to remotely attach to it, so a restart would be required to deploy the Java Agent. 
  • Installed: Installs the Java Agent but the Universal Agent does not attempt to deploy it to a JVM. Deploying to a JVM requires you to manually add the Java Agent to the JVM startup routine.

The following sections look at each of these options.  

Attach the Java Agent into Running JVMs

The remote attach feature enables the Java Agent to load itself into a running JVM, without a restart of the JVM or having to modify the JVM startup commands. 

Note the following points when using this feature:

  • The same requirements apply to using remote attach with the Universal Agent as apply when using it directly with the Java Agent. These requirements include the use of Oracle HotSpot JVM, for example. See Install the Java Agent for more information on these requirements. 
  • These conditions apply to the user under which the Universal Agent runs: 
    • On Windows, the Universal Agent must be running under the Local System account.
    • On Linux, the UA must be running either as root, as the same user the runs the JVMs, or must be authorized to use sudo. See more information below.

Note that remote attach can affect the performance of the application during the attachment initialization process. Be sure to use this feature only after careful testing in a staging environment. 

To attach the Java Agent into running JVMs: 
  1. Ensure that tools.jar is in the JAVA_HOME/lib/ext directory on monitored hosts.
  2. Set the "state" attribute for the matching Java agent rule in the rulebook to "attached."
  3. If the Universal Agent is not running as root or as the same user that runs the JVM, authorize the user for sudo privileges, as described below. 
  4. When using remote attach, it is likely that you will want to specify conditions for attaching the Java Agent to JVMs. For example, you can set conditions on installation based on startup commands that match Tomcat startup commands. Use the deploy_cmd and deploy_env_vars configuration attributes in the Java Agent rule for this type of control.

When you save the rulebook, the Universal Agent should begin to apply the rule change the next time it reads the active configuration. 

Authorizing a Non-Root Universal Agent User

If the Universal Agent runs as root or as the same user that runs the JVMs to which you want to remotely attach, no additional user configuration is required. However, if the Universal Agent runs as a non-root user that is not the same user used to run the target JVM, then you need to authorize the Universal Agent user to use sudo. Running with sudo privileges allows the Universal Agent to retrieve environment variables used in dynamic variable binding. 

In most Linux installations, you can configure sudo ability for the Universal Agent by editing the /etc/sudoers file using the 'visudo' tool. The following steps provide an example of this configuration change:

  1. Find the line with "Defaults requiretty" and change it to "Defaults !requiretty".
  2. Find the line with "rootALL=(ALL) ALL". After this line, add the line "<user> ALL=(ALL) ALL", where "<user>" is the user ID that the Universal Agent service is running under.
  3. At the end of the file, add the following line:
    "<user> ALL = NOPASSWD: /opt/appdynamics/universal-agent/ua, /usr/bin/java"
    Where "<user>" is the user id that the Universal Agent service is running under. Note that "/usr/bin/java" represents the fully-qualified path name for Java on this system; this value can be obtained by entering the "which java" command, and may be different from "/usr/bin/java".

Install the Java Agent Automatically at JVM Startup

When you set the state to "started," the Universal Agent examines each new process started on the host. If the process is a new JVM, the Universal Agent injects the javaagent argument into the startup arguments for the process. With this approach, you do not need to modify the Java startup script and it is supported on all JVMs types. This feature is also referred to as auto-java mode. 

Since this affects the JVM startup process, JVMs that are already running will not be affected. Also, the Java Agent version must be 4.2.3 or later.

AppDynamics Java Agent versions 4.2.6.x and 4.2.7.x include an issue that prevents the Universal Agent from being able to install those versions directly. The issue was addressed in Java Agent version 4.2.8.

If you are using version 4.2.6.x or 4.2.7.x, you can work around this incompatibility by having the Universal Agent first install Java Agent 4.2.8, or a later version. You do not need to deploy the later version to your application; simply create a rule for it with a state value of installed, while specifying attached or started as the state for the 4.2.6.x or 4.2.7.x agent rules.

If you are testing this feature on Linux, keep in mind, this feature relies on the Linux LD_PRELOAD facility, along with environment variables set in the JVM startup environment. Command shells that are open before you've enabled auto-java may not have the environment variables properly set.

On Windows, the auto-java feature is analogous to the LD_PRELOAD feature on Linux. When the auto-java feature is enabled, the Universal Agent gains visibility to the command line arguments for any new JVM process being started and adds two new arguments to the command line as follows:

  • -javaagent:<FQPN_javaagent.jar>, where <FQPN_javaagent.jar> is the fully qualified path name of the javaagent.jar file, as installed by the Universal Agent. The addition of this command line argument causes the Java agent to be loaded into the new JVM
  • -Dappdynamics.ua.rule.dir=<FQPN_UA_ rule_ dir>, where <FQPN_UA_ rule_ dir> is the fully qualified path name of the directory containing the Universal Agent rulebook.

If the Java command line arguments already contain the -javaagent argument, referring to the javaagent.jar file, or the javaagent.jar file can not be located, then the Universal Agent does not modify the Java command line.

To insert the Java Agent into the JVM at JVM start up
  1. Specify "started" as the value of the state property for the matching Java agent rule in the rulebook:
    1. Set the state property for the matching Java agent rule in the rulebook to "started."
    2. When using the "started" (or auto-java) mode, it is likely that you will want to specify conditions for attaching the Java Agent to JVMs.
      For example, you can set conditions on installation based on startup commands that match Tomcat startup commands. Use the deploy_cmd and deploy_env_vars configuration attributes in the Java Agent rule for this type of control. 
  2. Enable the auto-java feature by executing the following command from a command prompt:

    ua --enable-auto-java
  3. When you save the rulebook, the Universal Agent applies the rule change the next time it reads the active configuration.

See Universal Agent CLI for more details on the auto-java command line arguments.

Install the Java Agent Manually

Instead of relying on the Universal Agent to install the Java Agent into JVMs, you can modify the startup scripts for the JVM to inject the Java Agent. This is the traditional method for installing Java Agents, as described in Install the Java Agent. However, by using the Universal Agent, you can rely on it to manage the download and maintenance of the agent on the host.  

The Universal Agent CLI tool lets you inspect the arguments for a given Java process. You can use this to determine any other command line options that need to be added as well, in addition to the "-javaagent" option. Use the CLI command "ua --show-java-arguments <pid>" argument (where "<pid>" is the process ID of the target application JVM) to see what command line options are required. 

To install the Java Agent but inject into JVMs manually:
  1. Set the "state" attribute for the matching Java agent rule in the rulebook to "installed."
  2. Add the Java Agent JAR file to the startup routine of the JVM, as described for your Java framework type in Install the Java Agent. The agent JAR should be the Java Agent located in the <ua_home>/monitor/java directory. 

Java Agent Rule Matching

A rulebook can have multiple Java Agent rules. When applying rules, the Universal Agent applies the first rule that matches the JVM, ignoring other possibly matching rules.  

The "condition" attribute also affects rule selection. If the value of "condition" yields a value of "False", the rule is not applied for a JVM.

Since a single rule can match multiple JVMs, you should use the "auto node naming" feature to ensure that each matching JVM is given a unique node name. To do this, do not include the "node_name" attribute in the rule. Instead, either provide a "node_name_prefix" attribute to provide a node name prefix, or omit the "node_name_prefix" attribute to enable the controller to generate a node name using the default prefix. In either case, a unique node name is generated for the JVM.

Java Agent Rule Syntax Reference

Rulebook entry for the Java Agent is as follows:

Syntax of Java agent rule
{
    "name": "<name of rule>",
    "comments": "<comments>",
    "monitor": "java",
    "config":
    {
        "version": "<Java agent version>",
        "state": "installed | started | attached",
        "controller_host": "<name of host running controller>",
        "controller_port": "<controller primary port>",
        "account_name": "<controller account name>",
        "account_access_key": "<controller account access key>",
        "application_name": "<business application>",
        "tier_name": "<tier name>",
        "node_name": "<node name>",
        "node_name_prefix": "<node name prefix for auto-naming>",
        "deploy_cmd": "<regular expression matching Java command line>",
        "deploy_env_vars": "<regular expression matching JVM environmental variables>",
        "do_not_deploy_cmd": "<regular expression matching Java command line to be excluded>",
        "crash_age_threshold_days": "<prevents installation to JVMs with recent crash logs>",
		"runtime_directory": "...identifies the runtime directory for the Java agent...",
        "additional_props": "...additional properties to be passed to the JVM...",
        "kind": "...indicates whether or not IBM version of Java agent is to be installed..."
    },
    "condition": "<rule status>" "...boolean expression indicating status of this rule"
}

The name, comments, monitor, and condition values are common for all Universal Agent monitor rules, and have no special meaning for the Java Agent. See Universal Agent Rulebooks for information on these values.

The "config" object contains features and attributes specific for the Java Agent. The following table describes the config fields:

KeywordDescriptionExample
versionThe version of the Java Agent to run."version": "4.3.0.0"
state

Indicates how the Java Agent deploys itself into the target JVM. Also related to the auto-java feature. Valid values are installed, started and attached. For more information, see Deployment Options.

"started"
controller_host

The name of the controller host where the Java Agent should connect.

Optional. Can be inherited from the global Universal Agent config attribute, or from the Controller identified in the universalagent.yaml file.

"localhost"
controller_port

The contoller port number where the Java Agent should connect.

Optional. Can be inherited from the global Universal Agent config attribute, or from the controller identified in the universalagent.yaml file.

"8080"
account_name

The account name that is passed to the Controller when the Java Agent attempts to connect.

Optional. Can be inherited from the global Universal Agent config attribute, or from the controller identified in the universalagent.yaml file.

"customer1"

account_access_key

The account access key that is passed to the Controller when the Java Agent attempts to connect.

Optional. Can be inherited from the global Universal Agent config attribute, or from the controller identified in the universalagent.yaml file.

 If the account access key contains the '$' character, then you need to specify 2 '$' characters in this attribute value, as in the example. 

"SJ5b2m7d1$$354"
application_name

The application name to be provided by the Java Agent when it connects to the controller.

Optional. Can be inherited from the global Universal Agent "config" attribute if it is not provided.

"ACME Book Store Application"

tier_name

The tier name to be provided by the Java Agent when it connects to the controller.

Optional. Can be inherited from the global Universal Agent config attribute, or from the controller identified in the universalagent.yaml file.

"ECommerce Server"
node_name

The node name to be provided by the Java Agent when it connects to the controller.

Optional. if it is missing and the "node_name_prefix" attribute is provided, then the "node_name_prefix" is used to name the node of the JVM. 

If both the "node_name" or the "node_name_prefix" attributes are missing, then the "auto node name" feature is used to name the node. The controller provides a unique name for the node, using the tier name as a prefix for the node name. 

 "Node_8000"
node_name_prefix

Indicates that the Java Agent should use the "auto node name" feature to define a unique name dynamically for the JVM.

The value of the "node_name_prefix" attribute specifies a prefix for the generated node name; the controller supplies a suffix to make the node name unique. If the "node_name" attribute is specified, then the "node_name_prefix" attribute is ignored, and the "node_name" attribute explicitly names the node.

In the example Java Agent rule, "$network_hostname.Commerce" serves as a prefix. Notice that "$network_hostname" refers to a Universal Agent environment value, which the Universal Agent binds to a value at runtime. (Environment variable references always begin with '$').

If both the "node_name" or the "node_name_prefix" attributes are missing, then the "auto node name" feature is used to name the node. The controller provides a unique name for the node, using the tier name as a prefix for the node name. 

"Commerce"
unique_host_id

The value of the "appdynamics.agent.uniqueHostId" property.

Optional. Can be inherited from the global Universal Agent config attribute, or from the controller identified in the universalagent.yaml file.

"cart-machine"
deploy_cmd

A regular expression that identifies the JVMs that the rule applies to. This regular expression is matched against the command line arguments that are used to start the JVM. If the expression matches the command line, then this rule is considered a candidate for deploying the Java Agent within the JVM. If this attribute is not provided, then the contents of the command line are not used to select JVM for deployment.

If the "deploy_env_vars" attribute is also provided, then the value of that attribute must also match the set of environmental variables associated with the JVM.

If the "do_not_deploy_cmd" attribute is also provided, then JVMs whose command line arguments match the "deploy_cmd" argument are not considered candidates for deployment if the command line also matches the value of the "do_not_deploy_cmd" argument.  

In the example Java Agent rule, the "deploy-cmd" regular expression is looking for a Java property "node_type=commerce".  If the command line for a starting JVM matches the regular expression, it is considered a candidate for the rule. (However, because the "do_not_deploy_cmd" attribute is also specified in this example, the rule is not applied to a JVM if it's command line matches "deploy_cmd" but also matches "do_not_deploy_cmd". 

".*/TIER1TOMCAT/.*"
deploy_env_vars

A regular expression that identifies the JVMs that the rule applies to. The set of environmental variables associated with the JVM is formed into a string, consisting of "key=value" pairs, delimited by blanks, and sorted alphabetically based on the key name. If the resulting string matches the regular expression defined by the "deploy_env_vars" attribute, then this rule is considered a candidate for deploying the Java Agent within the JVM. If this attribute is not provided, then the contents of the environmental variables are not used to select JVM(s) for deployment.

If the "deploy_cmd" attribute is also provided, then the value of that attribute must also match the command line used to start the JVM.

 If the "do_not_deploy_cmd" attribute is also provided, then JVMs whose command line arguments match the "deploy_cmd" argument are not considered candidates for deployment if the command line also matches the value of the "do_not_deploy_cmd" argument.  

".*SHOULD_APPLY=true.*"

do_not_deploy_cmd

A regular expression that is used to exclude JVMs that the rule should not apply to. This regular expression is matched against the command line arguments being used to start the JVM. If the expression matches the command line, then this rule is explicitly excluded from being considered a candidate for deploying the Java Agent within the JVM.

In the example Java Agent rule, the regular expression will match those Java command lines that contain "-Dproduction=true". JVMs whose command lines match this expression are excluded from deployment for this rule.

".*-Ddo_not_apply=true.*"
crash_age_threshold_days

This attribute indicates that the Universal Agent should not remotely attach itself to a JVM in which there are one or more recent java crash log files. The value of this attribute represents the number of days since the crash log file was created in order to be considered 'recent'. For example, if a value of 10 is specified for this attribute, then only crash log files created in the last 10 days prevent the Universal Agent from attempting remote attach. Crash logs older than 10 days do not prevent the attempted attach.

If this attribute is not specified, then the Universal Agent does not look for recent Java crash log files, and does not use their presence to prevent remote attach attempts. 

 
additional_propsA comma-separated list of key=value pairs providing additional property definitions to be passed to the JVM. Passed to the JVM if the value of the state keyword is specified as either "started" or "attached". "additional_props": 
"appdynamic.agent.uniqueHostId=host"
kindUse this attribute when the IBM version of the Java agent is being deployed. The value should be "ibm". If the attribute is missing, then the non-IBM version of the agent is deployed. "kind": "ibm"


Dynamic Configuration Values

Configuration settings can be set to static or dynamic values. Dynamic values may be bound to environment variables or system properties from the target application JVM itself. This lets you name nodes, tiers, or applications based on JVM-specific variables. This is particularly useful for elastic environments, in which node or tier identity cannot be known in advance.

To reference dynamic elements in rules, use the following format: 

  • For Java environmental variables, prefix the variable name with "$javaenv_"; 
  • For system properties, use the syntax "${property-name}", where 'property-name' is the name of the Java system property.  

When determining whether or not a Java rule applies to a particular JVM, the Universal Agent extracts the values of each environment variable, and perform symbolic substitution into the config values in the rule for each "$javaenv_" reference. The Universal Agent doesn't resolve Java system properties within the configuration rule; instead, the references are resolved by the Java Agent itself when it starts running within the JVM.

Example

The following shows a rule with sample dynamic values:

{
    "name": "Java rule",
    "comments": "...comments...",
    "monitor": "java",
    "config":
    {
        "version": "4.3.0.0",
        "state": "attached",
        "application_name": "$javaenv_APP_NAME",
        "tier_name": "${tierName}",
        "node_name": "$javaenv_APP_NAME-$javaenv_NODE_NAME",
        "deploy_cmd": "...regular expression matching Java command line..."
    },
    "condition": "...boolean expression indicating status of rule..."
}

In this example, several of the attributes have values referencing either JVM environment variables or system properties:

  • "application_name": "$javaenv_APP_NAME" indicates that the value of the "application_name" config attribute is the value of the "APP_NAME" environmental variable within a JVM 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_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.

Suppose a JVM is started with the following commands:

export APP_NAME=MyApplication
export NODE_NAME=MyNode


java -DtierName=MyTier  -jar app.jar

If matched to the sample rule, the result would the following configuration bindings for the JVM:

  • "application_name": "MyApplication"
  • "tier_name": "MyTier"
  • "node_name": "MyApplication-MyNode"

Notes on Dynamic Configuration

  • References to Java system properties are not resolved by the Universal Agent when evaluating rule conditions, since the property values from the JVM are not available to the Universal Agent. 
  • For environment variable substitution, if a Java Agent is introduced into a JVM at startup time (as opposed to remote attach), the javaagent.jar file must be version 4.3 or later. Note that 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.

 

  • No labels