Agent Installer is in maintenance mode. Use Agent Management.

The Agent Installer requires microservices configuration performed by .

The Agent Installer simplifies deployment to instrument your applications faster. You can manage applications instrumented by the Agent Installer with minimal code changes in Monitoring Settings.

Agent Installer Linux and Windows Operating Systems

  • Deploys Java and Machine Agents. 

  • Automatically instruments applications.
  • Assigns unique names to tiers and nodes.
  • Upgrades and rollbacks the agents.

Deploys Machine Agents. 

You can deploy other agents using the Getting Started Wizard. 

Agent Installer Overview

The Agent Installer works with these items:

  • Agent Installer - Executable installer inside the appdynamics-zero-agent-<version>.zip. file (representing the Agent Installer Platform). The Agent Installer installs the Agent Installer Platform with Java, and Machine Agents on a system. You access the installer from the Controller UI.
  • Decorator - Library responsible for automatically instrumenting new processes with APM agents. The library auto-instruments the application and auto-names tiers and nodes for the Controller.
  • Agent Installer Platform - Software bundle that manages the Decorator, Java Agent, and Machine Agent. Enables automatic instrumentation and reports the status of various processes to the Controller UI. Collective term for the decorator, agent daemon, agent binaries.
  • Downloader - Script (zero-agent.sh) that downloads individual zip files containing the Java and Machine (if applicable) Agents, and Agent Installer Platform.
  • Watchdog - Agents installed with the Agent Installer can be managed with the Watchdog process. 
  • Updater - Responsible for the rollback and upgrade of the monitoring agents.
  • Agent Installer - Executable installer inside the appdynamics-zero-agent-windows-64-<version>.zip. file (representing the Agent Installer Platform). The Agent Installer installs the Agent Installer Platform with Machine Agent on a system. You access the installer from the Controller UI.
  • Agent Installer Platform - Software bundle that manages the Machine Agent. Send metrics to the Controller UI. Collective term for the agent daemon, agent binaries.
  • Downloader - Script (zero-agent.ps1) that downloads individual zip files containing the Machine Agent, and the Agent Installer Platform.
  • Watchdog - Agents installed with the Agent Installer can be managed with the Watchdog process. 
  • Updater - Responsible for the rollback and upgrade of the monitoring agents.

Agent Installer Requirements

The Agent Installer requires the following components, permissions, and supported environments. 

Applications will not instrument properly if file directories have their permissions changed by other processes, such as configuration management tools like Ansible.

Components

Configure and Unblock Your Firewall

You may need to configure your firewall rules to allow outgoing traffic to certain URLs including:

Agent Installer Permission

To configure access and roles, you must either be the Account owner, or have Administrator permissions. 

To use the Agent Installer, you need Install Agent account-level permission and at least one of the following:

Install Agent permission is not added to any default role.

Supported Environments

This table lists the Agent Installer supported environments. JVM and Application Server requirements only apply if you install the Java Agent. The Agent Installer does not support Windows installations.

Agent Installer Supported Environments
Operating System

Linux (64 bit). Fully tested flavors:

  • CentOS 7, 8
  • Rhel 7, 8
  • Ubuntu 18.04
  • Fedora 31
  • Debian 10

Other Linux operating systems and versions should work but are not certified by . 

Windows Server (64 bit). Fully tested flavors:

  • Windows 2019
  • Windows 2016

JVM (only on Linux)

  • Open => JDK 1.6
  • Oracle => JDK 1.7
  • IBM JDK => 1.6 

Application Server (only on Linux)

  • Apache Tomcat
  • Jboss Wildfly
  • GlassFish
  • Websphere
  • Weblogic

See Java Supported Environments and Machine Agent Requirements and Supported Environments for version compatibility. 

Agent and Process Limitations

This table lists the active agent registrations, process, and process group limitations for the Agent Installer:

AgentMaximum Per-Account Limit
Active agent registrations1000
ProcessMaximum Per-Account Limit
Managed processes10,000
Unmanaged processes10,000
Managed processes in a single installation100
Unmanaged processes in a single installation100
Process GroupMaximum Per-Account Limit
Managed process groups1000
Unmanaged process groups1000
Managed process groups in a single installation100
Unmanaged process groups in a single installation100

Available Agents with the Agent Installer

The Agent Installer deploys the Agent Installer Platform, which downloads monitoring agents to your machine. You can install: 

If you install Machine Agent on a host that doesn't have the application agent installed, then the Machine Agent works with the following: application name selected, tier name: your hostname, and node name: hostname <zero-agent-generated-hash-string>. 

Use the Agent Installer to Deploy an Agent

Application names cannot contain a single quotation mark ('). When you install Java JDK8+ with the Agent Installer, the OpenTelemetry resource attributes service.namespace and service.name are mapped to the application name and tier name. 

To use the Agent Installer to deploy an agent:

  1. From the Controller UI, select Home > Agent Installer.

  2. From the Specify Application to Deploy to dropdown, select an existing application, or select New application and enter its name.  

  3. Download and run the Agent Installer using either an express installation or a custom installation method. 

See Deploy an Agent Using the Agent Installer API. 

Express Installation Method

  1. The Express installation method is selected as the default. You can download and install the latest version of all available agents.  
    1. The Java Agent type, Java JDK8+, is the default for express installation with OpenTelemetry disabled. 
    2. The Machine Agent for express installation disables Server Visibility and .NET Compatibility Mode. 

  2. Copy and run the first command to download the latest available agents.  

  3. Select script icon (top right corner of the second command) to copy and run the second command to install the agents. Additionally, you can select Show command to reveal the full command with your access key.

  4. Restart the application processes you want to monitor. 
  5. Click Next to continue with the instrumentation. 

After you finish installing the agents, you are redirected to the Monitoring Settings tab to view instrumented tiers and nodes. 

Custom Installation Method

Your OpenTelemetry data may transit through regions different from where your Controller is hosted, if you configure your OpenTelemetry Collector using a endpoint located outside of the region, where your Controller is hosted. See Support for Cisco AppDynamics for OpenTelemetry™. 

  1. Select Custom installation. 

  2. Select the agents Java Agent (Legacy or JKD8+) or Machine Agent you want to install. 

  3. (Optional): Enable OpenTelemetry for Java Agent JDK8+. To do this, add traces exporter, metrics exporter, and OTLP Endpoint. 
  4. (Optional): Enable Server Visibility or .NET Compatibility Mode for the Machine Agent. 

  5. Copy and run the command into your terminal (on Linux) / PowerShell (on Windows) window or automated tools. 

  6. Determine how to run the Agent Installer by setting user permissions:

    • Select Instrument processes for all system users (requires sudo access) to run the Agent Installer with sudo permission and enable the Agent Installer Platform for all users on the host.

      • By default, the services run as root. To configure the services to run as a different user, add the parameter: --run-as <user>.
      • By default, the processes that run by all users will be instrumented. To instrument processes run by specific users, add the parameter: --filter-by-users <user1>,<user2>, or the parameter: --filter-by-groups <group1>,<group2>.

    • Select Instrument processes for an individual user to run the Agent Installer without sudo permission and enable the Agent Installer Platform for the current user only. See Sudo vs. Non-Sudo Access. 

    • By default the installed services run as the LOCAL SYSTEM. To configure the services to run as a local service account:

      • Add the run-as and password parameters for the Windows account.

      • If a service account is used (e.g. NT AUTHORITY\LOCAL SERVICE) then the password parameter will not be provided. Use a password that contains a minimum of sixteen characters. 

  7. After confirming the user installation permissions, select script icon (top right corner of the command) to copy and run the command. To reveal the full command with your access key, select Show command.

    1. When you run the command on a designated host, the agent files download onto that host only. To install agents on multiple hosts, select Run the Agent Installer on Multiple Hosts.

  8. Restart the application processes you want to monitor. 

  9. Click Next to continue with the instrumentation.

After you finish installing the agents, you are redirected to the Monitoring Settings tab to view instrumented tiers and nodes. 

Sudo Versus Non-Sudo Access (on Linux)

You can run the Agent Installer with or without sudo permission.

We recommend that you use the sudo command to install the agents for all users in your system. 

This table describes the differences between sudo and non-sudo installations:


sudo Installation

Non-sudo Installation

DescriptionInstalls the agents on all supported processes for all users in your system.Installs the agents for the current user only.
Automatic Instrumentation ProcessBy default, integrates with systemd to ensure the agents always run. See Customize Agent Installer to override this behavior.Auto-instruments processes that are started by the installing user, running under a Linux shell such as bash.

Instrument systemd-Managed Processes in a Non-sudo Environment

To enable the instrumentation of a systemd-managed application process in non-sudo Agent Installer Platform installations, the profile of the systemd service responsible used to load the application process must define the LD_PRELOAD environment variable using the path to the decorator library.

The actual path varies based on the operating system and product installation directory. This example shows an updated Apache Tomcat systemd service profile on CentOS 7:

$ grep LD_PRELOAD /etc/systemd/system/apache-tomcat-7.service Environment=LD_PRELOAD=/home/centos/appdynamics/zeroagent/lib64/libpreload.so

After the profile has been updated, you must reload the systemctl daemon and restart the application for the changes to take effect:

$ sudo systemctl daemon-reload 
$ sudo systemctl restart apache-tomcat-7.service

Run the Agent Installer on Multiple Hosts 

You can download the Agent Installer once and run on multiple hosts. To install the agent bundle across multiple hosts, distribute the binaries to all applicable machines. For example, these steps show how to move files across hosts using the tar command. 

  1. Download the agent bundle. See Use the Agent Installer to Deploy an Agent. 
  2. Distribute the Agent Installer to multiple hosts. 
    1. Make sure you are in the same directory in which you downloaded the agent bundle. 

    2. Use the tar command to place the script in a single file:

      tar cvf zero-agent.tar *

    3. Copy the file to multiple hosts:

      scp zero-agent.tar <target host>:<directory>

    4. Extract the archived script in the same directory:

      tar xvf zero-agent.tar
  3. Complete the Agent Installer deployment using the custom installation method.

Customize the Agent Installer

See Customize Agent Installer. 

Upgrade and Rollback the Agent Installer

See Upgrade and Rollback the Agents. 

Enable Server Visibility and .NET Compatibility Mode

See Enable Server Visibility and .NET Compatibility Mode with Agent Installer to enable Server Visibility and .NET Compatibility Mode for Machine Agent, using the configure command. 

Node Name Format 

The Node name format changes starting with versions >=22.4. Upgrading to version 22.4 automatically changes the Node name for the existing environment after restart. 

The <serverName> is applicable for the jboss appserver type.

Agent Installer VersionNode Name FormatNode Name Example
<22.4 <hostName>-<First 4 systemId><Last 4 systemId>-[hash of Tiername]-<serverName>ubuntu_host-sefd-er43-rextderutq
>=22.4<hostName>-<First 4 systemId><Last 4 systemId>-[hash of JavaUniquePath]-<serverName>ubuntu_host-sefd-er43-texdreodrx

For systems with the Machine Agent enabled, and not the Java Agent enabled, the Node and Tier name have the following format:

Node Name FormatNode Name Example
<hostName>-<First 4 agentId>-<Last 4 agentId>-[hash of agentId]centos7_j7-4c97-d243-e77979f4d4911864
Tier Name FormatTier Name Example

<hostName>

centos7_j7

Uninstall the Agent Installer 

To uninstall the Agent Installer in the terminal, navigate to the directory where the Agent Installer Platform is installed, and run the command:

languagebash<install-directory>/bin/zfictl uninstall
<install-directory>\bin\zfictl.exe uninstall