Administering the Instana agent on Docker

After you install the agent, configure and manage the agent as you require. See the following sections for all the available agent configuration options on Docker.

Checking the status of the host agent

After you install the host agent, you can check the status of the host agent in the Instana UI or on the host. For more information, see Checking the status of the host agent.

Configuring the agent

In addition to the required environment variables, additional environment variables can be configured during startup. For more information about available variables, see Environment variables for host agent.

Mount the main configuration files into the /root directory. The files are copied in place when the agent archive (.tar) file is unpacked.

Overriding agent configuration with volume mounts

You can override the settings swap in configuration files by using the Docker volume feature. The agent configuration file configuration.yaml that is provided with the image defines default values and might not be overwritten. You can extend the file by custom configuration snippets named configuration-<custom-extension>.yaml as follows:

--volume <host-path>/configuration-<custom-extension>.yaml:/opt/instana/agent/etc/instana/configuration-<custom-extension>.yaml

Example: You can set up a configuration-mysql.yaml file for the MySQL credentials and add this configuration file during container start.

configuration-mysql.yaml

# Mysql
com.instana.plugin.mysql:
  user: 'mysqlAdmin'
  password: 'mysqlSecretPassword'

docker run volume mount

--volume /opt/instana-agent/etc/instana/configuration-mysql.yaml:/opt/instana/agent/etc/instana/configuration-mysql.yaml

Configuring multiple backends

You can configure the Instana agent to report to multiple backends. For general considerations and notes about the configuration, see Configuring multiple backends.

To add additional backends to the Instana host agent, mount the backend files such as com.instana.agent.main.sender.Backend-2.cfg.

See the following example argument for a containerized agent:

--mount type=bind,source=<path-to-additional-backend-config>,target=/opt/instana/agent/etc/instana/com.instana.agent.main.sender.Backend-2.cfg

Configuring agent repository mirror

To use your own agent repository mirror, you must configure the dynamic agent by using INSTANA_MVN_REPOSITORY_URL, INSTANA_MVN_REPOSITORY_SHARED_PATH and INSTANA_MVN_REPOSITORY_FEATURES_PATH environment variables. For more information about using environment variables to configure the repository mirror, see the example in the Setting up agent repositories for dynamic host agents topic.

Configuring the agent for proxy settings

The Instana agent reaches out to two different endpoints; the Instana backend system for sending all collected data, and a repository for fetching agent and sensor updates. You can configure both of these endpoints to use proxy settings. The following three approaches are available:

No proxy settings for both endpoints — no configuration required for proxy settings.
Same proxy settings for both backend and repository — configure only the "Agent" proxy settings.
Different proxy settings for backend and repository — configure both proxies separately and make sure to set INSTANA_REPOSITORY_PROXY_ENABLED=true.

For example, if you need to configure a proxy only for the repository, use the following configuration:
- Set all INSTANA_AGENT_PROXY_ variables to "" (empty string).
- Set INSTANA_REPOSITORY_PROXY_ENABLED=true
- Set all INSTANA_REPOSITORY_PROXY_ variables to the proxy configuration as needed.

Similarly, for agent proxy settings, enable INSTANA_AGENT_PROXY_ENABLED and set all INSTANA_AGENT_PROXY_ variables to the proxy configuration as needed.

Updates and version pinning

You can control the agent updates and pin versions that you require by using environment variables. For more information, see Control updates in containerized agents.

Customizing the agent configuration

After you install the host agent, the following configuration files are created:

/opt/instana/agent/etc/mvn-settings.xml
/opt/instana/agent/etc/org.ops4j.pax.url.mvn.cfg
/opt/instana/agent/etc/instana/com.instana.agent.bootstrap.AgentBootstrap.cfg
/opt/instana/agent/etc/instana/com.instana.agent.main.config.Agent.cfg
/opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg
/opt/instana/agent/etc/instana/com.instana.agent.main.sender.Backend.cfg
/opt/instana/agent/etc/instana/configuration.yaml

You can customize the configuration of the agent as you need. For example, you can change the TCP port and hostname of the Instana backend and services that your host agent connects to, configure the agent to report to multiple backends, or configure a proxy for indirect communication from the host agent to the Instana backend.

For more information about customizing the agent configuration, see the following topics:

Starting and stopping the agent

Starting the agent

When you install the host agent, it is enabled to start automatically at system boot. You can turn off this behavior by setting the environment variable INSTANA_AGENT_AUTOSTART=false when you install the agent.

To start the host agent, run the following command:
```
INSTANA_AGENT_FOLDER/bin/start
```
If your operating system uses systemd as init system, run the following command:
```
systemctl start instana-agent.service
```
If your operating system uses SysVinit as init system, run the following command:
```
service instana-agent start
```

Stopping the agent

To stop the agent, run the following command:

INSTANA_AGENT_FOLDER/bin/stop

Managing agents by using the Agent Management dashboard

You can complete the following operations by using the Agent Management dashboard in the Instana UI:

To open the Agent Management dashboard, complete the following steps:

In the sidebar of the Instana UI, select Infrastructure.
Click a specific monitored host.
On the host dashboard, click Open Agent Management.

Enabling GPU monitoring

The following Nvidia graphic cards are supported.

Table 1: Supported graphic cards for GPU monitoring
Brand	Model
Tesla	S1070, S2050, C1060, C2050/70, M2050/70/90, X2070/90, K10, K20, K20X, K40, K80, M40, P40, P100, V100
Quadro	4000, 5000, 6000, 7000, M2070-Q, K-series, M-series, P-series, RTX-series
GeForce	varying levels of support, with fewer metrics available than on the Tesla and Quadro products

Prerequisites

You must use Linux OS for GPU monitoring.

Also, make sure that the following software are installed:

Docker version 19.03 or later.
The latest official Nvidia drivers. Drivers that are installed by using package managers are not sufficient.
NVIDIA Container Toolkit.

To enable GPU monitoring, start the Instana agent container on one or more GPUs. The agent can be started as a privileged container.

The agent collects metrics for all the system-wide available GPUs which are supported regardless of how many GPU(s) the agent is running.

For a detailed list of the collected metrics, see our GPU docs.

There are several ways to start the agent container using GPUs:

To start on all available GPUs, provide the --gpus all flag.
To start on the exact number of GPUs, provide the --gpus <number of gpus to use> flag.
To start on desired GPUs, provide the --gpus '"device=<gpu1-uuid>,<gpu2-uuid>"' flag.