Installing the host agent on AWS Elastic Beanstalk

Install the Instana host agent on your AWS Elastic Beanstalk environment to monitor and trace the JVM applications that are running in the environment.

See the following sections to see how to install and configure the agent on AWS Elastic Beanstalk:

Before you install

Before you install the Instana agent on AWS Elastic Beanstalk, make sure that you check the following guidelines:

Use m5.large or larger instance types for production environments. The default t3.micro instances might cause resource shortage issues.
Configure proper network connectivity (outbound communication) for the Instana agent. For more information, see Outbound network access requirements.

Installing the agent

Installing the Instana host agent on AWS Elastic Beanstalk includes the following steps:

Preparing the environment
Preparing a sample application
Verifying the agent installation

Preparing the environment

To prepare the environment, complete the following steps:

Open AWS Cloud Shell and install the Elastic Beanstalk CLI (EBCLI) by running the following commands:

git clone https://github.com/aws/aws-elastic-beanstalk-cli-setup.git

pip install virtualenv

python ./aws-elastic-beanstalk-cli-setup/scripts/ebcli_installer.py

Add the path to the EBCLI executable files to the ~/.bashrc file by running the following command:

echo 'export PATH="/home/cloudshell-user/.ebcli-virtual-env/executables:$PATH"' >> ~/.bashrc

Refresh the current Bash session by running the following command:
```
source ~/.bashrc
```
Verify the EBCLI installation by running the following command:
```
eb --version
```

Preparing a sample application

To prepare a Tomcat sample application, first download the sample application. Then, add the Instana agent configuration to the application.

Downloading the sample application

Create a working directory by running the following commands:
```
mkdir -p eb-tomcat1
cd eb-tomcat1
```

Download the Tomcat sample application by running the following commands:

wget https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/samples/tomcat.zip
unzip tomcat.zip

Adding Instana agent configuration

Create an .ebextensions directory by running the following command:
```
mkdir -p .ebextensions
```

Create the agent configuration file and configure it to install the Instana agent by using the one-liner script. See the following example:

cat > .ebextensions/instana-agent.config << 'EOF'
commands:
  01_install_instana:
    command: |
      curl -o setup.sh https://setup.instana.io/agent && chmod +x setup.sh && ./setup.sh -a <INSTANA_AGENT_KEY> -t dynamic
EOF

Replace <INSTANA_AGENT_KEY> with your Instana agent key.

The one-liner script installs and configures the Instana agent.

Then, you can create and initialize your Elastic Beanstalk environment by using the eb init command or the AWS console.

Notes:

If you use Amazon Linux 2023, you must also provide the GP3 disk configuration. See the following example:


	cat > .ebextensions/storage.config << 'EOF'
	option_settings:
		aws:autoscaling:launchconfiguration:
			RootVolumeType: gp3
	EOF

If you want to configure environment variables, use the following command:


	cat > .ebextensions/environment.config << 'EOF'
	option_settings:
		aws:elasticbeanstalk:application:environment:
			SERVICE_NAME: "beanstalk-tomcat"
	EOF

Verifying the agent installation

After you install the agent, verify the agent installation and check logs.

To verify the agent installation, first connect to the EC2 instance by running the following command:
```
eb ssh
```
Check the agent status by running the following command:
```
sudo systemctl status instana-agent
```    <br>
```

See the following sample response:

```bash {: codeblock}
● instana-agent.service - "Instana(tm) agent."
    Loaded: loaded (/usr/lib/systemd/system/instana-agent.service; enabled; preset: disabled)
    Drop-In: /etc/systemd/system/instana-agent.service.d
            └─agent-custom-start.conf, custom-environment.conf
    Active: active (running) since Thu 2025-03-06 16:06:29 UTC; 7s ago
  Main PID: 3675 (java)
      Tasks: 28 (limit: 9245)
    Memory: 170.3M
```

You can also check the agent on the Instana UI by opening the Infrastructure map and checking for traces.

Checking logs

To check the agent log files, run the following commands:

```bash {: codeblock}
cd /opt/instana/agent/data/log/

cat agent.log
```

To clear the logs and see only the latest entries, run the following commands:

```bash {: codeblock}
sudo systemctl stop instana-agent

sudo rm agent.log

sudo systemctl start instana-agent
```

Modifying Instana agent configuration

After you set up the environment and install the Instana agent, you can further modify the agent configurations by completing the following steps:

On the AWS Cloud Shell, open the Instana configuration directory. See the following example:
```
cd /opt/instana/agent/etc/instana/
```
Check the configuration by running the following command:
```
ls -la
```
Edit the configuration file by running the following command:
```
sudo vi configuration.yaml
```
To apply the changes, restart the agent by running the following command:
```
sudo systemctl restart instana-agent
```

Troubleshooting the agent installation

If you cannot install the agent successfully at first, you can check log messages and troubleshooting tips. For more information about troubleshooting host agents, see Troubleshooting.

See the following commonly observed issues with Instana agent installation on AWS Elastic Beanstalk and their solutions:

Agent connection issues

If you notice issues with agent connection, try the following methods:

Verify whether the Instana agent key is correct.
Check connectivity from the EC2 instance to the Instana backend.
Verify your security group settings.

Java application tracing issues

If you notice issues with Java application tracing, try the following methods:

Verify that the Java sensor is enabled.
Check Java version compatibility.