AppDynamics Application Intelligence Platform

3.9.x Documentation

PDFs

Learn by Watching

Doc Maps

Standalone Machine Agent - Overview of Running Remediation Scripts - 0:48

 

A remediation action runs a local script in a node. The script executes on the machine from which it was invoked or on the node specified by the remediation action configuration. You can use this type of action to automate your runbook procedures.

By default the script is a shell script in /bin/sh invoked with the -ex option, unless the script has a header, in which case the interpreter in the header is used. For example, if the script header is "#!/bin/perl", the PERL interpreter is invoked.

You can optionally configure the remediation action to require human approval before the script is started. See Actions Requiring Approval.

Remediation actions can be performed only on machines that are running the machine agent. See Install the Standalone Machine Agent.

Prerequisites for Local Script Actions

  • The Standalone (Java-based) Machine Agent must be installed running on the host on which the script executes.
    To see a list of installed machine agents for your application, click View machines with machine-agent installed in the bottom left corner of the remediation script configuration window.
    See Install the Standalone Machine Agent if you need to install a machine agent.
  • To be able to run remediation scripts, the machine agent must be connected to an on-premise Controller or to a SaaS Controller via SSL. Remediation script execution is disabled if the machine agent connects to a SaaS Controller on an unsecured (i.e., non-SSL) HTTP connection.
  • The machine agent OS user must have full permissions to the script file and the log files generated by the script and/or its associated child processes.
  • The script must be placed in a sub-directory of the machine agent installation directory that is named "local-scripts".
  • The script must be available on the host on which it executes.
  • Processes spawned from the scripts must be daemon processes

Remediation Scripts

A remediation script is run on the machines that you specify in the remediation script configuration. You can run the script from the machine affected by the violation that triggered the action or from a central management server. It is not necessary for an app agent to be running on the machine on which the script executes, just a machine agent.

Guidelines for Remediation Scripts

A process exit code of zero indicates that the script execution succeeded. A non-zero exit code indicates that it failed.

The script should be written as generically as possible to allow it run on any of the nodes for which is it invoked. AppDynamics exports the following environment variables to the script runtime to provide context regarding the environment and the event that triggered the action.

Environment Variable

Cardinality (1 or N)

Notes

APP_ID

1

Name of the Application

EVENT_TIME

1

Timestamp of the event

EVENT_ID

1

Event Id

EVENT_TYPE

1

type of event, such as: ERROR, APPLICATION_ERROR, APPLICATION_INFO, STALL, BT_SLA_VIOLATION, DEADLOCK, MEMORY_LEAK, MEMORY_LEAK_DIAGNOSTICS, LOW_HEAP_MEMORY, ALERT, CUSTOM, APP_SERVER_RESTART, BT_SLOW, SYSTEM_LOG, INFO_INSTRUMENTATION_VISIBILITY, AGENT_EVENT, INFO_BT_SNAPSHOT, AGENT_STATUS, SERIES_SLOW, SERIES_ERROR, ACTIVITY_TRACE, OBJECT_CONTENT_SUMMARY, DIAGNOSTIC_SESSION, HIGH_END_TO_END_LATENCY, APPLICATION_CONFIG_CHANGE, APPLICATION_DEPLOYMENT, AGENT_DIAGNOSTICS, MEMORY, LICENSE

ENV_STARTUP_ARGS

1

Process args

ENV_SYSTEM_PROPERTIES

1

JVM System Props (When Java)

AFFECTED_ENTITY

1

Affected Entity that triggered the event

Troubleshooting Remediation Scripts

To troubleshoot your remediation script, look for the process in the machine agent log. The log is located at

<Machine_Agent_Installation_Directory>/logs/machine-agent.log

The snippet below from the machine agent log shows both error and success messages from running a local script named "script.sh".

Remediation Example

The following remediation action, named increasePool, executes  a local script named runbook.sh, which increases the size of the connection pool on the JVM.

A policy named ConnectionPoolPolicy triggers this action when the Resource Pool Limit Event fires:

Creating a Local Script (Remediation) Action

To create a local Script Action

1. Follow the instructions in To create an action, selecting Remediation->Run a script or executable on problematic Nodes in the Create Action window.
2. Enter a name for the action.
3. In the field that terminates the Relative path to script entry, enter the rest of the path to the executable script.
Remediation scripts must be stored in a sub-directory of the machine agent installation. The sub-directory must be named "local-scripts". The following paths are all valid:

${machine.agent.directory}/local-scripts/runMe.sh
${machine.agent.directory}/local-scripts/johns_scripts/runMe.sh
${machine.agent.directory}/local-scripts/ops/johns_scripts/runMe.sh

4. Click the + to enter the absolute paths of any log files that the script writes to that you want included in the script output.
5. Enter the timeout period for the script process in minutes.
6. If you want to require approval before the script action can be started, check the Require approval before this Action check box and enter the email address of the individual or group that is authorized to approve the action. See Actions Requiring Approval for more information.
7. Click OK.

To specify the nodes on which the action will run

When you bind the action to a policy, you specify the nodes on which the script should execute. You can configure the number of nodes or the percentage of nodes or you can configure a specific node. This flexibility allows you to configure scripts to run from a central management server, not just the node on which the violation occurred.

In the Configure Action window, do one of the following:

1. Select Execute Action on Affected Nodes.
2. Enter the percentage of the nodes or the number of nodes on which to run the script.

or

1. To designate the specific node on which to run the script, select Execute Action on Specified Node.
2. Click Select Node.
3. From the popup node browser select the node on which the script should run.
4. Click Select.
The selected node is displayed in the Configure Action window.
5. Click Save to save the configuration.
Click Change if you want to designate a different node.

To see the output of the local script

1. Click Events in the left navigation pane to navigate to the Events list.
2. Locate the row for the event that triggered the action for which you want to see the results.
3. In the Actions column, click the remediation script icon.

4. In the script result list, select the script output that you want and click Download Local Script Result.

Learn More