Installing the Agent on Docker

The Instana agent requires Docker version 1.11 or higher.

The Instana agent can be executed as a privileged container via the following command:

sudo docker run \
  --detach \
  --name instana-agent \
  --volume /var/run:/var/run \
  --volume /run:/run \
  --volume /dev:/dev \
  --volume /sys:/sys \
  --volume /var/log:/var/log \
  --privileged \
  --net=host \
  --pid=host \
  --ipc=host \
  --env="INSTANA_AGENT_KEY=your Instana agent key" \
  --env="INSTANA_AGENT_ENDPOINT=the monitoring ingress endpoint" \
  --env="INSTANA_AGENT_ENDPOINT_PORT=the monitoring ingress endpoint port" \

In the above command, you can also include the following optional variables:

  --env="INSTANA_AGENT_ZONE=the zone name of the host" \
  --env="INSTANA_AGENT_TAGS=comma separated list of host tags" \
  --env="INSTANA_DOWNLOAD_KEY=Instana download key" \
  --env="INSTANA_AGENT_UPDATES_VERSION=pin the Sensor versions to a specific SHA" \
  --env="INSTANA_AGENT_UPDATES_FREQUENCY=control the frequency at which Sensor updates are fetched" \
  --env="INSTANA_AGENT_UPDATES_TIME=control the time at which Sensor updates are fetched" \
  --env="INSTANA_AGENT_PROXY_HOST=hostname/address of a proxy" \
  --env="INSTANA_AGENT_PROXY_PORT=port of a proxy" \
  --env="INSTANA_AGENT_PROXY_PROTOCOL=proxy protocol e.g. http" \
  --env="INSTANA_AGENT_PROXY_USER=username of the proxy auth" \
  --env="INSTANA_AGENT_PROXY_PASSWORD=password of the proxy auth" \
  --env="INSTANA_AGENT_PROXY_USE_DNS=the boolean if the proxy also does DNS" \
  --env="INSTANA_REPOSITORY_PROXY_ENABLED=enable overriding proxy settings specifically for Sensor updates" \
  --env="INSTANA_REPOSITORY_PROXY_HOST=hostname/address of a proxy for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PORT=port of a proxy for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PROTOCOL=proxy protocol for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_USER=username of the proxy auth for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PASSWORD=password of the proxy auto for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_USE_DNS=boolean if proxy also does DNS" \

Please adapt the INSTANA_AGENT_KEY, INSTANA_AGENT_ENDPOINT and INSTANA_AGENT_ENDPOINT_PORT variables to your setup. The others (setting Zone, Tags, Proxy) are optional. Please see Agent Configuration for details.

Once running, the agent log will be available via docker logs instana-agent. The main configuration files can be mounted into the /root directory, and will be copied in place once the agent tarball is unpacked.

Override Agent Configuration with Volume Mounts

It is possible to swap out agent configuration files via the Docker volume feature. For instance, to change the artifact repository endpoint, add the following parameter:

--volume <host-path>/org.ops4j.pax.url.mvn.cfg:/opt/instana/agent/etc/org.ops4j.pax.url.mvn.cfg

The agent’s configuration.yaml provided with the image defines default values and may not be overwritten. It may be extended by custom configuration snippets named configuration-<custom-extension>.yaml like this:

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

One example use case would be to have a configuration-mysql.yaml for the MySQL credentials and add this configuration file during container start.


# 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

Configure Multiple Backends

The first backend configuration for docker based agents is populated from environment variables. For additional configurations, volume mount the appropriate configuration file starting with com.instana.agent.main.sender.Backend-2.cfg.

An example argument for a dockerized agent is:

--volume <path-to-additional-backend-config>:/opt/instana/agent/etc/instana/com.instana.agent.main.sender.Backend-2.cfg

Agent Proxy Settings

The Instana Agent reaches out to two different endpoints, being our backend system for sending all collected data, and a repository for fetching Agent and Sensor updates. Both can (separately) be configured for using proxy settings. In all, there are 3 options:

  1. No proxy settings for both endpoints - no need to configure any proxy settings
  2. Same proxy settings for both backend and repository - only need to configure the ‘Agent’ proxy settings
  3. Different proxy settings for backend and repository - configure both proxies separately and make sure to set INSTANA_REPOSITORY_PROXY_ENABLED=true

In case you for example only need to configure a proxy for the repository, use the following configuration:

  • Set all INSTANA_AGENT_PROXY_ variables to "" (empty string).
  • Set all INSTANA_REPOSITORY_PROXY_ to the proxy configuration as needed. The same applies the other way around, when only needing a proxy for the backend and not the repository.

Updates and Version Pinning

Using the INSTANA_AGENT_UPDATES_VERSION, INSTANA_AGENT_UPDATES_FREQUENCY and INSTANA_AGENT_UPDATES_TIME environment variables its possible to control whether Agent sensor versions get pinned to a specific version, and allows controlling when new updates are fetched. See Agent Configuration documentation for more information about these settings.

Possible options for the parameter INSTANA_AGENT_UPDATES_FREQUENCY are:

  • DAY (for daily updates)
  • MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY or SUNDAY Multiple options can be supplied, separated by a colon.

Enable GPU monitoring

The following Nvidia Graphic Cards are supported.

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

Supported OS: Linux.


  • Minimum Docker version 19.03.
  • Latest official Nvidia drivers are installed. Drivers installed through package managers are not sufficient.
  • NVIDIA Container Toolkit is installed (

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.