Installing the Agent on a Host

Instana agent is a regular Java process at its core. The packages for all our supported operating systems only differ in a few native libraries shipped with it. Instana only provides automatic installation or service management scripts for Linux , Windows and Containerized Environments.

Other Supported OS

The Instana Agent itself however also supports the following operating systems:

  • Mac OS 64 bit
  • Solaris SPARC 32/64 bit
  • AIX PowerPC 32/64 bit
  • z/OS Unix System Services
  • z/OS Linux on s390x

Manual Download Installation

The Instana agent must be installed in a system-wide accessible location, ideally run as the root user. Running the agent with any other user limits its functionality because some of the performance metrics are only supported by the root, and monitoring docker containers can only be done by the root on the docker host machine. Also, only either the root or startup user are capable of attaching and monitoring Java Virtual Machines (JVMs).

The user that is running the agent needs to be able to write in the agent directory and all its subdirectories. The agent will download the required sensors depending on the auto detection, and create log files in its “data” subdirectory. Please ensure about 100 MB of free disk space.

Prerequisites

Java 8 must be available.

A Java 8 Development Kit (JDK 8) needs to be available for the agent. There are two options:

  1. The easiest is to place or link that JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

  2. The customizable way is to export an environment variable called JAVA_HOME to point to that JDK (this environment variable can be also set via instana-agent-install-dir>/bin/setenv).

At the moment, the following JVMs are supported for running the agent:

It is important that the JVM is executable for any user on the system. We recommend using the latest available patch release of the Java distribution of your choice. Be advised that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. Using such a package will result in errors like “java.lang.RuntimeException: Could not generate DH key pair.”

Agent Communication

The agent will download updates and sensors from the following host:

DNS Name: artifact-public.instana.io; Destination Port: tcp/80 and tcp/443.

We currently provide the Instana Service from two different regions. Your individual instance will be located geographically closest to the majority of your agents and users. Agents are preconfigured when downloaded, but there are additional installation methods that require configuring the Instana Backend. Please consult the Agent Management section inside the product or your technical contact at Instana to learn about the region where your instance is located.

  • Europe:

    • DNS Name: saas-eu-west-1.instana.io
    • Destination Port: tcp/443
  • United States and Rest of the World:

    • DNS Name: saas-us-west-2.instana.io
    • Destination Port: tcp/443

Note: Even though the IP addresses are static, please use the DNS names wherever possible.

Agent Download

To install, simply download and extract the agent archive matching your system architecture.

You can access the portal for download just after logging in to Instana itself. Click on the profile picture in the top right corner to access the Management Portal. This will lead directly to the download section. Just select the appropriate operating system in the dropdown menu and download the agent. It is automatically preconfigured with your account settings so that you just have to extract and start the agent.

Limitations on MacOS

We provide a best effort compatibility with MacOS for development and testing purposes. Please note that you must run the agent as regular user account, not as root, and it will only monitor processes run by the same user. Running the agent in a Docker container is not supported. Finally, monitoring of Docker containers is not possible due to significant differences in internals of Docker Machine and Docker for Mac to the regular Linux Docker.